> [!IMPORTANT]
> **AI Assist Note (Knowledge Heritage)**:
> This document is part of the "Sovereign Reality" documentation.
> - **@docs ARCHITECTURE:Documentation**
> - **Failure Path**: Information drift, legacy terminology, or documentation mismatch.
> - **Telemetry Link**: Search `[OPERATIONS_MANUAL]` in audit logs.
>
> ### AI Assist Note
> Core technical resource for the Tadpole OS local business infrastructure, adapted for Small & Medium Business (SMB) use.
>
> ### 🔍 Debugging & Observability
> Traceability via `parity_guard.py`.

> [!NOTE]
> **Branding Note**: This document and the system glossary reflect the transition of the legacy "Sovereign Reality" product name to the canonical "Tadpole OS" branding. Legacy terms are redirected where appropriate.

# 🧠 Tadpole OS: Business Operations Manual (SMB Edition)

> **Deployment Class**: Small & Medium Business (SMB) Local Node  
> **Status**: Verified Production-Ready  
> **Version**: 1.1.423  
> **Last Hardened**: 2026-08-16 (catalog validation, lock safety, and documentation governance)
> **Last Verified Against Codebase**: v1.1.421 working tree on 2026-08-16
> **Data Privacy**: 100% Local-First / Zero Data Leaks  
> **Last Code/Docs Parity Check**: 2026-08-16

---

## 📖 Terminology & Business Concepts

To navigate the local swarm engine of Tadpole OS, business operators must understand the core concepts that drive the virtual teams.

### Tier 1: Operator
- **Department Lead** (formerly Alpha Node) [DEFINE: Alpha Node]: The orchestrating agent in a workspace responsible for breaking down goals, recruiting specialist sub-agents, and compiling reports.
- **Project Workspace** (formerly Mission Cluster) [DEFINE: Mission Cluster]: A collaborative local directory grouping multiple virtual agents and shared assets toward a single business goal.
- **Private Swarm Environment** (formerly Sovereign Reality) [DEFINE: Sovereign Reality]: The secure, local-first runtime environment where virtual agents execute business processes under human control.
- **Department Scope** [DEFINE: Department Scope]: A communications constraint in the SovereignChat that restricts broadcasted instructions to all agents and sub-agents assigned to a specific workspace folder or cluster.

### Tier 2: Admin
- **Swarm Depth** [DEFINE: Swarm Depth]: The levels of delegation from the business operator down to terminal specialist nodes (Recommended Max: 3 for standard office hardware; Absolute Max: 5, configurable via `MAX_SWARM_DEPTH`).
- **Agent Scope / RAG Scope** [DEFINE: RAG Scope]: The data ingestion context constraint limiting an agent's retrieval to specific files, workspace directories, or long-term memory.
- **Mode-Switched Utility Cluster** [DEFINE: Mode-Switched Utility Cluster]: A consolidated multi-role agent team template with strict operational boundaries and sub-routine mode switching, designed to minimize database index bloat and state synchronization latency across the swarm.
- **Team Cluster Preset** [DEFINE: Team Cluster Preset]: A reusable workspace configuration detailing a team cluster name, badge tag, default USD budget, department, and assigned multi-role agent collaborators.

### Tier 3: Security
- **Secure Vault** (formerly Neural Vault) [DEFINE: Neural Vault]: The encrypted, client-side repository for all LLM API keys and provider credentials. Auto-locks after **30 minutes** of inactivity and syncs unlock state across browser tabs via `BroadcastChannel`.
- **Swarm Pulse** [DEFINE: Swarm Pulse]: A real-time binary telemetry event stream showing system communications, agent thinking state, and tool calls.

> [!TIP]
> **Complete Lexicon**: For a full technical breakdown of system terms, refer to the [GLOSSARY.md](./GLOSSARY.md). Every term marked with a `[DEFINE:]` tag corresponds to a high-fidelity entry in the glossary.

---

## 🗺️ Operational Tiers (Table of Contents)

### Tier 1: The Business Operator (Dashboard & Daily Ops)
*For team managers directing virtual agents.*
- [1. Multi-Tab Business Interface](#1-multi-tab-business-interface)
  - [1.1 The Multi-Tab Bar](#11-the-multi-tab-bar)
  - [1.2 Unified Dashboard Header](#12-unified-dashboard-header)
  - [1.3 Directing Agents via Chat & Voice](#13-directing-agents-via-chat--voice)
    - [1.3.1 Business Chat Portal](#131-business-chat-portal-sovereignchat)
    - [1.3.2 Voice Interface](#132-voice-interface-voiceclient--standups)
    - [1.3.3 Swarm Visualizer Interaction](#133-swarm-visualizer-interaction)
    - [1.3.4 Activity Lineage Stream](#134-activity-lineage-stream-lineage_stream)
- [2. Project & Folder Management](#2-project--folder-management)
  - [2.1 Defining Project Goals](#21-defining-project-goals-missions)
  - [2.2 Shared Directories & File Assets](#22-shared-directories--file-assets-workspaces)
  - [2.3 Operations Center & Command Chain](#23-operations-center--command-chain-ops_dashboard)

### Tier 2: The Systems Administrator (Config & Cost Control)
*For managing engine parameters, API keys, and local hardware.*
- [3. Shared Folder & Asset Management](#3-shared-folder--asset-management)
  - [3.1 Workspace Manager](#31-workspace-manager-workspaces)
  - [3.2 Dynamic Environment Detection & OKF Governance](#32-dynamic-environment-detection--okf-governance)
  - [3.3 Task Draft Branching Workflow](#33-task-draft-branching-workflow)
- [4. Core Intelligence Management Suite](#4-core-intelligence-management-suite)
  - [4.1 LLM Provider Configuration](#41-llm-provider-configuration-model_manager)
  - [4.2 Custom Virtual Employee Profiles](#42-custom-virtual-employee-profiles-agentconfigpanel)
  - [4.3 Local Data Synchronization (RAG)](#43-local-data-synchronization-rag-search_mission_knowledge)

### Tier 3: Security & Performance Optimization
*For budget-guarding, hardware tuning, and diagnostics.*
- [5. Security, Approvals & Budget Safeguards](#5-security-approvals--budget-safeguards)
  - [5.1 Oversight Gate & Approval Queue](#51-oversight-gate--approval-queue-oversight)
    - [5.1.1 The Approval Queue](#511-the-approval-queue)
    - [5.1.2 Emergency Controls](#512-emergency-controls)
    - [5.1.3 Passive Mirror Mode (Digital Twin)](#513-passive-mirror-mode-digital-twin)
  - [5.2 Security Dashboard & Cost Quotas](#52-security-dashboard--cost-quotas)
  - [5.3 Secure Credentials Vault](#53-secure-credentials-vault)
  - [5.4 Client-Side API Resilience (Circuit Breaker)](#54-client-side-api-resilience-circuit-breaker)
- [6. The Workspace Heartbeat (Observability)](#6-the-workspace-heartbeat-observability)
  - [6.1 Visualizing the Team and Codebase](#61-visualizing-the-team-and-codebase-engine_dashboard--swarm_visualizer)
  - [6.2 Neural Footprint & Token Cost Monitoring](#62-neural-footprint--token-cost-monitoring-command_table)
  - [6.3 Parity Guard CLI](#63-parity-guard)
  - [6.4 Latency Benchmarks & Dual-Trace Analytics](#64-latency-benchmarks--dual-trace-analytics-benchmark_analytics)

- [Appendix A: Daily Operational Workflows](#appendix-a-daily-operational-workflows)
- [Appendix B: Maintenance & Local Backups](#appendix-b-maintenance--local-backups)
  - [B.1 Directory Structure & Backups](#b1-directory-structure--backups)
  - [B.2 Automatic Hardware Recovery](#b2-automatic-hardware-recovery)
  - [B.3 Global Environment Variables](#b3-global-environment-variables)
  - [B.4 Build Feature Flags](#b4-build-feature-flags)

---

## 1. Multi-Tab Business Interface

The primary navigation system of Tadpole OS, allowing for multi-context orchestration within a single, high-performance web dashboard. **Multi-Monitor Friendly**: All tabs can be detached into separate windows for distributed oversight across dual office displays.

> [!NOTE]
> **Runtime Governance Anchor**: All persistence paths (workspaces, local databases, and temporary caches) resolve from the backend `AppState.base_dir`, ensuring local-dev and server-mounted office networks use the same folder root.

### 1.1 The Multi-Tab Bar
Located permanently at the top of the viewport, the Multi-Tab Bar manages your active workspaces:
- **Dynamic Contexts**: Tabs represent individual operational sectors (Dashboard, Projects, Team Graph, Settings).
- **Context Preservation**: Switching tabs preserves the state of each page, enabling seamless multitasking.
- **Detachable Portals**: Click the **External Link** icon revealed on hover to pop out any tab into a native browser window for dual-monitor layouts.
- **Header Sync**: The global `PageHeader` automatically updates its action controls to match the active tab.

**Interactive Elements:**
- **[Button] Detach/Recall tab**
  - *Default state*: Embedded (Not Detached).
  - *Visible location*: Right-hand side of individual tab headers in the Multi-Tab Bar when hovered.
  - *Observable side effect*: Spawns a new browser window hosting the page, replacing the embedded view, and changes the icon to a minimize/recall icon.
- **[Button] Close tab**
  - *Default state*: Open.
  - *Visible location*: Far right of hovered tab headers in the Multi-Tab Bar.
  - *Observable side effect*: Closes the selected tab and shifts focus to the next available active tab.

### 1.2 Unified Dashboard Header (`PageHeader`)
A persistent command surface at the top of the page:
- **Engine Status**: Real-time local connection status (**🟢 ONLINE**).
- **Page-Specific Actions**: Direct action shortcuts (e.g., "Start New Project" when on the Projects tab).
- **Core Metrics**: High-level telemetry tailored to the active operation, synchronized via the `useEngineStatus` hook.

### 1.3 Directing Agents via Chat & Voice

#### 1.3.1 Business Chat Portal (`SovereignChat`)
The primary natural language interface for issuing directives to your virtual departments. It supports granular audience targeting:
- **Agent Scope** [DEFINE: RAG Scope]: 1:1 communication with a selected virtual employee. Context is limited to that agent's specific role memory.
- **Department Scope** [DEFINE: Department Scope]: Department-wide instructions (e.g., `#marketing`).
- **Global Scope** [DEFINE: Swarm Pulse]: Broadcasts messages to all active agents.

**Command Syntax:**
- **Standard Input**: Type a message and hit `Enter` to send in the active scope.
- **Targeted Agent**: Use `@AgentName <Message>` to send a task to a specific agent regardless of active scope.
- **Targeted Department**: Use `#DepartmentName <Message>` to broadcast to all agents in a specific work folder.

**Interactive Elements:**
- **[Toggle] Safe Execution**
  - *Default state*: `false` (Unchecked, allowing safe-mode execution configurations via `is_safe_mode`).
  - *Visible location*: Bottom command bar of the `SovereignChat` panel.
  - *Observable side effect*: When enabled, enforces strict approval requirements, blocking agents from performing modifications without explicit confirmation in the Oversight queue.
- **[Button] Detach Interface**
  - *Default state*: Embedded (Not Detached).
  - *Visible location*: Top-right header of the `SovereignChat` panel.
  - *Observable side effect*: Spawns a new native browser portal window containing the chat widget, retaining full state synchronization.
- **[Button] Minimize Dock**
  - *Default state*: Maximized (Open).
  - *Visible location*: Top-right header of the `SovereignChat` panel (minimize icon).
  - *Observable side effect*: Collapses the chat panel into a floating circular button in the bottom-right corner of the viewport.
- **[Selector] Scope Tab**
  - *Default state*: `'agent'` (Active scope).
  - *Visible location*: Sub-header row of the `SovereignChat` panel.
  - *Observable side effect*: Swaps active context filtering and targets between Agent, Department (Cluster), and Global (Swarm) scopes.
- **[Breadcrumb] Lineage path**
  - *Default state*: `'Overlord'` root.
  - *Visible location*: Directly below the scope selector in `SovereignChat` when the Agent tab is active.
  - *Observable side effect*: Visualizes parent-to-child delegation lines for the active virtual employee.

### 1.4 Neural Map & Cognition Visualizer Operations

The **Neural Map** provides real-time 2D force-graph visualization of structural codebase references (Tree-sitter AST symbol nodes) and semantic OKF knowledge networks. Clicking any node opens the **Cognition Sidebar Inspector** (`CognitionSidebar.tsx`), displaying high-fidelity operational metadata:

- **Topic Space** (`<hash>/<relative_path>`):
  - Displays the obfuscated workspace hash prefix followed by the relative file path.
  - Enforces **Security Policy SEC-05 (Path Obfuscation)**: Absolute local paths are salted and hashed on the backend before UI rendering to prevent filesystem path leakage.
- **Concept Type** (`general`, `sop`, `playbook`, `metric`, `symbol`):
  - Categorizes the node according to the Open Knowledge Format (OKF v0.2) taxonomy.
  - Denoted by monochromatic Lucide iconography in the sidebar.
- **Confidence Score** (`0%` to `100%`):
  - The Multi-Factor Scoring (MFS) confidence decay metric.
  - Newly ingested structural AST nodes start at `0%` baseline until validated by active agent mission execution. Human-authored directives and active SOPs carry high confidence (80%–100%).
- **Governance State** (`Confirmed` vs `Pending Review`):
  - Evaluates Sapphire Shield Zero-Trust operator verification (`human_confirmed` flag).
  - **🟢 Confirmed**: Manually verified by an operator (`human_confirmed = true`).
  - **🟡 Pending Review**: Autonomously ingested node awaiting human operator sign-off (`human_confirmed = false`).

#### 1.4.1 Static Code Anomalies Panel (`AnomalyPanel.tsx`)

Embedded directly within the Neural Map HUD, the **Anomalies Panel** tracks structural code health and static analysis findings detected by the Tree-sitter AST engine during workspace indexing.

* **Primary Purpose**:
  - **Dead Code & Drift Detection**: Identifies unused symbols (`UNUSED_SYMBOL`), unreferenced functions, dangling imports, and disconnected nodes across Rust and TypeScript files.
  - **Automated Refactoring Prompts**: Features a one-click **"Copy Prompt"** button (`anomaly_prompt_template`) that compiles all active workspace anomalies into a formatted refactoring instruction set, ready for submission to an AI agent swarm.
  - **Interactive Node Jump**: Clicking any listed anomaly centers and highlights the corresponding node directly on the 2D Neural Map graph for visual blast-radius inspection.

**Interactive Elements:**
- **[Button] Copy Prompt**
  - *Default state*: Active (`anomaly_prompt_template`).
  - *Visible location*: Top header controls of `AnomalyPanel.tsx`.
  - *Observable side effect*: Copies formatted static analysis anomalies into the clipboard, ready to paste into `SovereignChat` for automated refactoring.
- **[Card] Anomaly Node Item**
  - *Default state*: Unselected list row.
  - *Visible location*: Scrollable list inside the Anomalies Panel HUD.
  - *Observable side effect*: Centers and highlights the corresponding AST symbol node on the 2D Neural Map graph for visual blast-radius inspection.
- **[Filter] Anomaly Severity Selector**
  - *Default state*: All Severities.
  - *Visible location*: Header filter row of `AnomalyPanel.tsx`.
  - *Observable side effect*: Filters displayed static code findings by severity classification (Critical, Warning, Info).

**Keyboard Shortcuts:**
- **Toggle Command Palette**: `[Shortcut: Ctrl+K]` or `[Shortcut: Ctrl+/]` (toggles the global utility search bar, cited in [useLayoutNavigation.ts:L51-83](../src/hooks/layout/useLayoutNavigation.ts#L51-L83)).
- **Tab Quick-Navigation**: `[Shortcut: 1-6]` (Quick-routes to: 1. Dashboard, 2. Org Chart, 3. Standups, 4. Workspaces, 5. Docs, 6. Settings when input fields are out of focus, cited in [useLayoutNavigation.ts:L51-83](../src/hooks/layout/useLayoutNavigation.ts#L51-L83)).

→ *See §5.3 for vault security details.*

#### 1.3.2 Voice Interface (`VoiceClient` / `Standups`)
A voice-driven extension providing hands-free inputs and a dedicated "Standup Meeting" portal for team coordination.

**Core Interface Elements:**
- **Status Header**: Displays connection state (e.g., `SECURE LIVE CHANNEL` vs `Ready for Voice`).
- **Target Selection Matrix**: A control box for defining voice handshake destinations.
    - **Toggle (Agent Node)**: Restricts the voice input to a single virtual employee.
    - **Toggle (Workspace Cluster)**: Broadcasts the voice capture to all agents assigned to a specific folder.
    - **Selection Dropdown**: A precision list of active agents or department IDs.
- **Volume Visualizer**: A multi-spectrum bar graph reflecting local audio input levels.
- **Connection Command Bar**:
    - **[Button] Start/End Channel**
      - *Default state*: Inactive (`'idle'`).
      - *Visible location*: Center console of the `VoiceClient` pane.
      - *Observable side effect*: Opens or terminates local microphone streaming buffers, updating state metrics to live recording.
    - **[Button] Local Mic Mute**
      - *Default state*: Unmuted (`false`).
      - *Visible location*: Next to the connection button on the command bar.
      - *Observable side effect*: Mutes microphone capturing lines without severing the audio interface connection.
- **Live Transcript Log**:
    - **Identity Attribution**: Color-coded identifiers showing speakers (`U` for User, `A` for Agent).
    - **Active Telemetry**: Displays `REC` (Recording) vs `IDLE` status and real-time "Agent X is speaking..." feedback.

→ *See §4.1 for provider configuration.*

#### 1.3.3 Swarm Visualizer Interaction
The **`SovereignChat`** is integrated with the visual **Team Graph**. Clicking any virtual employee node on the graph automatically focuses that agent's project context in the chat, allowing for instant coordination.

#### 1.3.4 Activity Lineage Stream (`Lineage_Stream`)
A real-time telemetry sidebar that visualizes the propagation of data and instructions through your virtual organization.
- **Real-time Feed**: Scrollable timeline of every agent event, tool execution, and system message.
- **Chain of Command Tracker**: Visualizes the path an instruction took from the Department Lead down to the final terminal agent.
- **Payload Panel**: Displays the raw text content of individual agent thoughts and actions.

**Interactive Controls:**
- **[Sidebar] Resizable Boundary**
  - *Default state*: Fixed standard width.
  - *Visible location*: Outer border of the Lineage Stream drawer.
  - *Observable side effect*: Expands or contracts the sidebar panel width.
- **[Card] Event Node**
  - *Default state*: Unselected.
  - *Visible location*: Scrolling logs within the stream.
  - *Observable side effect*: Triggers and opens the high-density Cinematic Depth View overlay.
- **[Overlay] Cinematic Depth View**
  - *Default state*: Closed (`false`).
  - *Visible location*: Center-screen modal overlay.
  - *Observable side effect*: Displays the selected agent's full parameters, outputs, and JSON payloads.

#### 1.3.5 Outward Customer Catalog & A2A Gateway (`/customer-catalog`)
A dedicated, siloed management hub for SMB owners to configure public customer-facing AI agents and expose `a2a-protocol.org` compliant agent cards (`company-agent-card.json`).

**Core Features & Interfaces:**
- **Silo Isolation Barrier**: Completely isolates customer-facing agent interactions from internal engineering codebase symbol graphs and system files.
- **Outward Local Model Runner**: Binds customer agent execution to local model profiles (`gemma4:e4b`, `gemma4:e8b`, `gemma4:full`) for low-latency, zero-cloud-leak customer inquiries.
- **Catalog Import Boundary**: CSV and QuickBooks JSON are validated before shared catalog state is locked. Imports are capped at 512 KiB per field, malformed or empty payloads return RFC 9457 `BAD_REQUEST`, and a failed import leaves the catalog unchanged. PDF ingestion is unavailable and the interface directs operators to export CSV or QuickBooks JSON instead of reporting fabricated success.
- **Authentication & Profile Sync**: `POST /a2a/v1/catalog/import` and `PUT /a2a/v1/profile` require the configured bearer token. The manager saves profile changes through the shared authenticated API client after a 300 ms debounce and cancels superseded requests. Public discovery and search remain token-free and use a 60-request-per-minute IP fixed window.
- **Business FAQ & Operating Info Card Manager (`Company_Info_Card_Manager.tsx`)**:
    - **Interactive CRUD Cards**: Create, edit, and delete business knowledge cards (FAQ, Operating Info, Policies, Custom) dynamically.
    - **Tabbed Category Filter**: Filter knowledge cards instantly by category tab (`All`, `FAQ`, `Operating Info`, `Policies`, `Custom`).
    - **Real-Time PII & Luhn Algorithm Guard**: Live form warning alert detecting credit card numbers (validated via Luhn Mod-10 algorithm), Social Security Numbers, and secret API keys before saving.
    - **Delete Confirmation Shield**: Employs system-wide `Confirm_Dialog` modal for safe deletion confirmation.
- **Published A2A Company Agent Card Preview (`A2A_Card_Preview`)**: Live visual preview displaying exposed agent skills compiled from knowledge cards, version, copyable well-known JSON endpoint URL (`http://localhost:8000/a2a/v1/company-agent-card.json`), and active local model profile.

---

## 2. Project & Folder Management

### 2.1 Defining Project Goals (`Missions`)
Clear project scoping ensures virtual teams execute tasks quickly and stay within your budget:
- **New Project**: Initialize standard business objectives.
- **Scope Parameters**: Define the target goal, constraints, and outputs.
- **Assign Team**: Select which virtual employee profiles to assign to the project folder.
- **Collaboration Graph**: SVG-rendered diagram showing how agents will interact and delegate.

#### Project Lifecycle Status States
Swarm missions transition through a strict state machine representing different phases of execution:
- **Pending**: The project has been created by the operator but has not yet been initiated.
- **SpecReview**: The Department Lead agent reviews the project goals, scopes the recipes, and validates the required inputs and skills before beginning work.
- **Active**: Specialists are actively executing tools, processing documents, and reasoning in the workspace sandbox.
- **Completed**: The primary goal is achieved, and a final summary report is compiled by the Department Lead.
- **Failed**: The swarm encountered a terminal error, exceeded the budget, or reached maximum delegation depth.
- **Paused**: Processing is temporarily suspended by the operator or awaiting manual oversight resolution.

Child specialists share the parent mission ledger but cannot close it independently. Each branch records its own cost and structured outcome (`completed`, `failed`, `blocked`, or `cancelled`). If any branch is incomplete, the Department Lead preserves successful work, pauses the parent mission, and presents it for human retry, resume, or closure. Independent Conductor steps may run concurrently in bounded waves; steps whose dependencies fail remain visibly blocked instead of being reported as successful.

#### Workspace Cluster Limits & Concurrent Execution
To prevent system overload on local nodes, operators can run **multiple concurrent active clusters** simultaneously. Active clusters process missions in parallel up to the `MAX_CLUSTERS` engine cap (default: `10`). If the active workspace count matches this limit:
- Any attempts by the operator to initialize a new project workspace are blocked.
- A warning log is emitted by the system: `Cluster limit reached` (logged as level `'warning'` by [workspace_service.ts:L65-68](../src/services/workspace_service.ts#L65-L68)).

#### 2.1.1 Mode-Switched Utility Clusters & Team Management Studio
To reduce database index sizes, configuration loading times, and state synchronization latency across large swarms, operators can group multi-role agents into **Mode-Switched Utility Clusters**:
- **Concurrent Swarm Execution**: Multiple mission clusters can be toggled to `ACTIVE` simultaneously, executing parallel swarm operations across isolated work folders without forced single-active deactivations.
- **Cluster Studio (`[CLUSTERS]`)**: Accessible via the `CLUSTERS` studio button next to `+ NEW MISSION` on the Missions sidebar. Opens the **Utility Cluster Configuration Studio** modal ([Cluster_Manager_Modal.tsx](../src/components/missions/Cluster_Manager_Modal.tsx)) to define reusable team presets with custom badge tags (e.g. `SEC-AUDIT`, `ENG-SWARM`), budget allocations, and multi-role agent memberships.
- **Deploying Team Presets (`+ ADD TEAM CLUSTER PRESET`)**: Inside the `NEW MISSION` creation drawer, operators can expand the team preset gallery to populate pre-configured team parameters in a single click.
- **Editable Pre-fill Collaborator Toggle**: Selecting a team preset pre-fills all defined multi-role agents into an interactive checkbox list, allowing operators to fine-tune assigned collaborators before creating the project workspace.
- **Sidebar Team Badges**: Active project workspace cards displaying multi-role team presets render a high-visibility `🏷️ [TEAM: BADGE]` tag below the budget readout for instant visual identification.

→ *See §4.1 for provider configuration.*

### 2.2 Shared Directories & File Assets (`Workspaces`)
Centralized coordination of local storage paths, department folders, and local files:
- **Department Folders**: Shared folders grouping virtual employees by function (e.g., Marketing, Bookkeeping).
- **Lead Assignee**: The primary manager agent responsible for final reports compiling.
- **Local Scan**: Auto-scans local workspaces for active developer files, spreadsheets, or text logs.

→ *See §4.3 for local data synchronization details.*

### 2.3 Operations Center & Command Chain (`Ops_Dashboard`)
The central nervous system for monitoring running processes and hardware loads:
- **Operations Center**: Real-time agent status dashboard and engine health checks.
- **Org Chart**: Visual graph of the command chain from Department Lead to sub-agents.
- **Scheduled Jobs**: Manage recurring tasks (e.g., scraping weekly invoices, building weekly status updates).

→ *See §5.2 for security dashboard and cost quota details.*  
→ *See §6.1 for the swarm visualizer that powers the Org Chart.*  

---

## 3. Shared Folder & Asset Management

### 3.1 Workspace Manager (`Workspaces`)
Centralized coordination of project storage paths and shared files.

**Operational Features:**
- **Department Clusters**: Workspaces that group virtual employees by department (Accounting, Marketing, Admin) into shared local folders.
- **Lead Node Halo**: Every cluster highlights the primary leader agent (gold outline) responsible for overall project execution.
- **Environment Detection**: Automatically detects host runtime sandboxes, developer shells, and container configurations.

→ *See §4.3 for local data synchronization details.*

### 3.2 Dynamic Environment Detection & OKF Governance

To ensure safety during execution, Tadpole OS runs a dynamic telemetry engine to detect host runtime environments and validate them against security rules specified in Open Knowledge Format (OKF) playbooks:

- **Dynamic Environment Detection**:
  - Automatically probes the host for sandboxes (`docker`, `wasm_sandbox`), execution interfaces (`tauri_shell`, `vs_code`, `jupyter_lab`), and orchestration environments (`k8s_node`, `headless`).
  - Displays detected platforms on the Workspaces dashboard using monochromatic Zinc-scaled badges to minimize visual clutter while retaining full environment observability.

- **OKF Playbook Safety Gates**:
  - Active workspaces are checked against security rules declared in OKF playbooks (e.g., `requires: docker` or `requires: k8s_node`).
  - If a required host environment is missing (e.g., Docker daemon is offline but a playbook requires containerization), the validation state transitions to `warning` or `critical`, presenting a high-contrast safety warning banner on the dashboard in semantic colors (`cyber-amber` or `cyber-red`).

- **Playbook Auto-Mounting & Caching**:
  - The backend engine resolves active OKF playbooks assigned to a cluster's ID and automatically mounts them to the cluster's directory on disk as a read-only local JSON file (`playbooks.json`), allowing local agents to access playbooks and constraints without direct database queries.
  - Active playbooks are rendered on the dashboard as clickable badges that deep-link to the **Semantic OKF Graph** page for visual inspection of Institutional Knowledge Store (IKS) relationships.

**Interactive Elements:**

- **[Card] OKF Playbook Badge**
  - *Default state*: Populated with the mounted playbook's title.
  - *Visible location*: "OKF Governance" card inside the Workspace Cluster details.
  - *Observable side effect*: Clicking deep-links to `/knowledge?node=<id>` to display its node relationships in the Semantic OKF Graph.
  - *Keyboard shortcut*: None.
  - *Missing in build*: Always present.

- **[Banner] Safety Alert Banner**
  - *Default state*: Hidden (Nominal).
  - *Visible location*: Middle section of the "OKF Governance" card inside the Workspace Cluster details when validation status is `warning` or `critical`.
  - *Observable side effect*: Renders error details and missing environment requirements.
  - *Keyboard shortcut*: None.
  - *Missing in build*: Always present.

### 3.3 Task Draft Branching Workflow
- To protect your core documents from mistakes, virtual employees do not edit primary business files directly.
- Agents write proposed edits to temporary draft files (e.g., `report_draft.md`).
- A draft queue appears on the Workspaces dashboard waiting for the operator's approval.

**Interactive Elements:**
- **[Button] Approve Draft**
  - *Default state*: Pending approval.
  - *Visible location*: Proposal card inside the Workspace Manager dashboard.
  - *Observable side effect*: Overwrites the canonical file with the draft contents and clears the proposal from the active list.
- **[Button] Reject Draft**
  - *Default state*: Pending approval.
  - *Visible location*: Proposal card inside the Workspace Manager dashboard.
  - *Observable side effect*: Deletes the draft file, cancels the operation, and feeds rejection parameters to the agent.

→ *See §5.3 for vault security details.*

---

## 4. Core Intelligence Management Suite

These configuration pages manage provider API keys, local models, and virtual employee configurations.

### 4.1 LLM Provider Configuration (`Model_Manager`)
The credential manager for local and cloud AI providers.

> [!IMPORTANT]
> Accessing API keys requires typing your master passphrase. Credentials are encrypted using **PBKDF2 + AES-256-GCM** via the browser's native `SubtleCrypto` API and stored in browser `localStorage`. Encryption runs in a **background Web Worker** (`crypto.worker.ts`) to prevent UI lag during large workspace operations.

> [!CAUTION]
> **Browser Secure Context Requirement (`http://192.168.x.x:5173`)**:
> The Web Crypto API (`crypto.subtle`) strictly requires a **Secure Context** (`https://` or `http://localhost`). Accessing the dashboard remotely over plain HTTP (e.g., `http://10.0.0.1:5173`) will cause browser security policies to disable Web Crypto, preventing the Neural Vault from unlocking. For remote deployment access, configure HTTPS/TLS certificates or connect through a local SSH tunnel or reverse proxy.

☁️ REQUIRES NETWORK
> **External Cloud Connections**: Triggering generation queries on external cloud providers sends prompt payloads and decrypted API tokens directly to the provider endpoints. The currently supported cloud endpoints (with their env-var keys) are:
> - `api.openai.com` (`OPENAI_API_KEY`) — cited in [provider.rs:L384](../server-rs/src/agent/runner/provider.rs#L384) & [model_manager.rs:L172](../server-rs/src/routes/model_manager.rs#L172)
> - `api.anthropic.com` (`ANTHROPIC_API_KEY`) — cited in [anthropic.rs:L116](../server-rs/src/agent/anthropic.rs#L116) & [model_manager.rs:L126](../server-rs/src/routes/model_manager.rs#L126)
> - `generativelanguage.googleapis.com` (`GOOGLE_API_KEY`) — cited in [gemini.rs:L142](../server-rs/src/agent/gemini.rs#L142) & [model_manager.rs:L135](../server-rs/src/routes/model_manager.rs#L135)
> - `api.groq.com` (`GROQ_API_KEY`) — cited in [groq.rs:L136](../server-rs/src/agent/groq.rs#L136) & [model_manager.rs:L171](../server-rs/src/routes/model_manager.rs#L171)
> - `api.inceptionlabs.ai` (`INCEPTION_API_KEY`) — key resolution cited in [provider.rs:L393](../server-rs/src/agent/runner/provider.rs#L393)
> - `api.deepseek.com` (`DEEPSEEK_API_KEY`) — key resolution cited in [provider.rs:L396-414](../server-rs/src/agent/runner/provider.rs#L396-L414)
> - `api.replicate.com` (`REPLICATE_API_KEY` - used for semantic audio replicate caching) — cited in [res.rs:L51-53](../server-rs/src/state/hubs/res.rs#L51-L53)
>
> **Zero Leaks Pledge**: Payload structures are processed completely in memory; plaintext keys are never written to disk or logged by Tadpole OS.

**Interactive Elements:**
- **[Input] Master Passphrase**
  - *Default state*: Empty string (`""`).
  - *Visible location*: Center modal panel when Vault is locked.
  - *Observable side effect*: Dispatches key derivation routines inside the Web Worker.
- **[Button] Commit Authorization**
  - *Default state*: Enabled.
  - *Visible location*: Next to the passphrase entry field.
  - *Observable side effect*: Unlocks the provider configuration view, loading active API profiles.
- **[Button] Emergency Vault Reset**
  - *Default state*: Enabled.
  - *Visible location*: Bottom actions corner of the unlocked Vault panel.
  - *Observable side effect*: Destructive action that purges all local storage API keys and resets vault settings.
- **[Button] Add Provider**
  - *Default state*: Enabled.
  - *Visible location*: Top header of the provider listing page.
  - *Observable side effect*: Appends a configuration template card to the UI.
- **[Card] Provider Card**
  - *Default state*: Populated with configured URL and status.
  - *Visible location*: Main provider grid.
  - *Observable side effect*: Expands inputs for URL endpoints, API keys, and custom providers.
- **[Table] Model Inventory**
  - *Default state*: Auto-scanned list of system-integrated models.
  - *Visible location*: Center region of `Model_Manager`.
  - *Observable side effect*: Displays feature matrix capabilities.
- **[Toggle] Show Limits**
  - *Default state*: Collapsed (`false`).
  - *Visible location*: Row elements inside the Model Inventory table.
  - *Observable side effect*: Exposes RPM and TPM threshold configurations.

#### 4.1.1 Secure Context Requirements
The vault uses the browser's standard **SubtleCrypto API**, requiring a **Secure Context**:
- **Local Access**: `localhost` and `127.0.0.1` are secure by default.
- **Remote Access**: Accessing the dashboard via a local network IP (e.g., `http://10.0.0.1:5173`) will disable credential features. You must set up **HTTPS** to access the vault remotely.

#### 4.1.2 Automated Capability Inference (IMR-01)
The engine automatically detects the feature set of your models:
- 👁️ **multimodal**: Supports processing images, diagrams, and PDFs.
- 🛠️ **tools**: Supports tool execution (e.g., writing files, calculations).
- 🧠 **reasoning**: Optimized for deep analytical logic (e.g., DeepSeek-R1, OpenAI o1/o3).

→ *See §5.3 for vault security details.*

#### 4.1.3 Remote Companion Pairing and Revocation

Open **Remote Oversight & Mobile Mesh Settings** while authenticated with the
desktop `NEURAL_TOKEN`, then select **Display Pairing QR Code**. Token creation
must succeed on the engine before the QR dialog opens; there is no client-side
fallback token. Scan the QR code in the companion app, then select **Refresh
Pairing Status**. The desktop lists a device only after the engine confirms its
registered Ed25519 public key.

Edits and revocations are also server-confirmed. If an operation fails, the
device remains unchanged in the interface and the error banner identifies the
failure. Revoked companions immediately lose signed-route access. Companion
requests require `X-Device-Id`, `X-Timestamp`, `X-Nonce`, and `X-Signature`;
stale or replayed requests are denied.

On Android, both approval and rejection decisions require biometric or device
credential confirmation. A failed registration, signature, or server command
must leave the displayed authoritative state unchanged; retry after confirming
the desktop address and that the device has not been revoked.

### 4.2 Custom Virtual Employee Profiles (`AgentConfigPanel`)
Set up virtual employees and define their scope of work:
- **Cognition Tab**: Toggle whether the agent retains long-term memory across sessions.
- **Governance Tab**: Set individual budget caps, toggle the "Requires Oversight" setting, and configure A2A Economic Zone daily spend limit caps to restrict micropayment transfers.
- **Inference Tuning**: Assign specific models and temperature parameters.
- **Reasoning Engine (Mythos)**: Tune the agent's internal monologue settings:
    - **Reasoning Depth (1-16 turns)**: Set to `1-4` for simple, quick tasks (e.g., email categorization). Set to `5-10` for complex analysis.
    - **ACT Halting Threshold**: Define the model's self-halting confidence level.

→ *See §5.1 for oversight queue details.*

### 4.3 Local Data Synchronization (RAG) (`search_mission_knowledge`)
The data intelligence layer synchronizes your local folders and databases with the agent's memory store.
- **Multi-Factor Scoring (MFS)**: Combines vector semantics, project relevance, and document recency to find the most accurate records.
- **Data Crawling**: System sync workers automatically index changes in your mapped directories every few minutes (`SME_SYNC_INTERVAL_MINS`).
- **Markdown SOP Enforcement**: Place your business Standard Operating Procedures (SOPs) as markdown files in `data/workflows/` to force agents to follow strict execution rules.

---

## 5. Security, Approvals & Budget Safeguards

### 5.1 Oversight Gate & Approval Queue (`Oversight`)
The primary dashboard safety valve that keeps the business operator in control of all agent actions.

#### 5.1.1 The Approval Queue
- **Pending Actions**: Displays actions (like rewriting files, executing local scripts, or browsing the web) that require explicit confirmation before running.
- **[Button] Approve / Reject**
  - *Default state*: Waiting.
  - *Visible location*: Individual tool request cards in the Oversight timeline.
  - *Observable side effect*: Resolves the backend blocking promise, either allowing the tool payload execution (`approved`) or returning a cancellation trace to the agent loop (`rejected`).

#### 5.1.2 Emergency Controls
> [!CAUTION]
> **Definitive System Termination**: These buttons trigger immediate thread suspension or service termination. Use with care.

- **[Button] Halt Agents**
  - *Default state*: Enabled/Online.
  - *Visible location*: Oversight dashboard header panel.
  - *Observable side effect*: Prompts the user with `confirm_halt_agents` dialog, then halts all active agent thinking loops by sending thread abort signals via the `handle_kill_switch` handler.
- **[Button] Kill Engine**
  - *Default state*: Enabled/Online.
  - *Visible location*: Oversight dashboard header panel.
  - *Observable side effect*: Prompts the user with `confirm_kill_engine` verification, demands typing the uppercase word `"SHUTDOWN"` in the text input, and then terminates the Axum service process immediately via the `handle_kill_engine` handler.

#### 5.1.3 Passive Mirror Mode (Digital Twin)
- **Passive Observation**: When the system is operated as a digital twin shadowing live systems, the operator can enable Mirror Mode by setting `MIRROR_MODE=true` in the environment (`.env`).
- **Drift Alerts & Interception**: Under Mirror Mode, any attempt by an agent to execute a mutating or dangerous tool (such as modifying filesystem files, running terminal scripts, or writing to external connections) is intercepted. Instead of executing the mutation:
  - The tool execution is blocked safely.
  - A drift alert entry is registered in the engine state.
  - An `oversight:drift` event is broadcasted over WebSockets to notify the dashboard in real-time.
  - A warning message is returned to the agent's context explaining that the passive twin boundary was enforced.
- **Mirror Mode Status API**: Operators can query `GET /v1/engine/mirror/status` to fetch the current mirror mode configuration and list of active drift alerts.

### 5.2 Security Dashboard & Cost Quotas
The dashboard tracks hardware safety and cloud costs:
- **[Gauge] Budget Quotas**
  - *Default state*: `0.0` USD used.
  - *Visible location*: Upper metrics grid of the Oversight dashboard.
  - *Observable side effect*: Dynamically reflects real-time cumulative LLM API expenses against configured caps.
- **[Metric] Swarm Health**
  - *Default state*: Perfect health indicator.
  - *Visible location*: Center-right of the metrics grid.
  - *Observable side effect*: Evaluates execution failures and warns of service namespace breakers tripping.
- **[Alert] RAM/VRAM Pressure**
  - *Default state*: Inactive.
  - *Visible location*: Diagnostics monitoring segment.
  - *Observable side effect*: Emits amber/red warning banners when system RAM or GPU memory utilization approaches VRAM limits.
- **[Toggle] Auto-Approve Safe Skills**
  - *Default state*: `true` (Enabled).
  - *Visible location*: Security settings panel on the `Oversight` page.
  - *Observable side effect*: When active, automatically permits standard read/search actions, queueing only write or shell tool calls.

### 5.3 Secure Credentials Vault
All external API connections use the client-side **`use_vault_store`** framework. API keys are encrypted with **PBKDF2 + AES-256-GCM** and stored in browser `localStorage` under the key `tadpole-vault-secrets`. Plaintext keys are decrypted only in memory during active runs — never written to disk or transmitted to the server.

**Key Security Behaviors:**
- **Auto-Lock**: The vault automatically locks after **30 minutes** of inactivity, clearing the master key from memory.
- **Cross-Tab Sync**: The vault uses a `BroadcastChannel` (`tadpole-vault-sync`) to synchronize unlock state across all open browser tabs. Unlocking in one tab unlocks all others.
- **Crypto Offloading**: All encryption/decryption is performed inside a background **Web Worker** (`crypto.worker.ts`), preventing UI lag on large key operations.

### 5.4 Client-Side API Resilience (Circuit Breaker)

<!-- Last verified against tag/commit v1.1.165 (commit adb41393) on 2026-06-11 -->

To shield the front-end dashboard from backend service failures, network timeouts, or offline logical bunkers, the application implements a client-side **Circuit Breaker** system for all core service namespaces (e.g., `infra`, `engine`, `continuity`).

#### 5.4.1 Breaker States & Behaviors
- **CLOSED**: Normal operation. All API requests pass through to the backend service.
- **OPEN**: Triggered when a service namespace encounters 5 consecutive failures (`VITE_SYSTEM_BREAKER_FAILURE_THRESHOLD` [RISK: HIGH]). In this state, further calls to the namespace are instantly rejected on the client side with a `CircuitBreakerOpenError` to prevent UI freezing.
  - *UI Visibility when OPEN*: The dashboard header ticker updates to **🔴 DISCONNECTED (RETRYING IN 10s)**, a toast notification alerts `🚨 Circuit Breaker OPEN: Service [namespace] temporarily offline`, and action buttons requiring that service namespace enter a disabled retry state until probing completes in `HALF_OPEN`.
- **HALF_OPEN**: After a 10-second cooldown period (`VITE_SYSTEM_BREAKER_COOLDOWN_MS` [RISK: HIGH]), the breaker enters a probe state, permitting a single request to test the backend's health. If the request succeeds twice, the breaker resets to **CLOSED**. If the request fails, it trips back to **OPEN** and starts a new cooldown.

#### 5.4.2 Log Observability
- 📡 `[Circuit Breaker] NAMESPACE entered HALF_OPEN probe state` - The cooldown expired, and the system is probing the service namespace.
- ❌ `[Circuit Breaker] NAMESPACE tripped back to OPEN from HALF_OPEN due to trial failure` - The health probe failed, indicating the service is still down (e.g., local Rust engine is stopped).

---

## 6. The Workspace Heartbeat (Observability)

### 6.1 Visualizing the Team and Codebase (`Engine_Dashboard` + `Swarm_Visualizer`)
A real-time force-graph visualizer showing how your agents interact and how your project files depend on each other. Accessible via the **Engine** sidebar item.
- **Pulse Indicators**: Visualizes real-time communication messages via a 10Hz binary telemetry stream.
- **Navigation Controls**: Move backward and forward through your traversal path, similar to web browser navigation.
- **High-Res Export**: Download high-quality PNG charts of your workflow hierarchies directly from the canvas.
- **Detach & Recall**: Pop the visualizer into a dedicated browser window for persistent multi-monitor oversight. Recall it back from the placeholder panel on the main dashboard.

### 6.2 Neural Footprint & Token Cost Monitoring (`Command_Table`)
A cost-accounting dashboard for monitoring API expenses. The `Command_Table` component is embedded in the **Oversight** page:

**Interactive Elements:**
- **[Table Row] Interaction Logs**
  - *Default state*: Populated with recent prompt-response pairs.
  - *Visible location*: Center region of the `Command_Table` panel.
  - *Observable side effect*: Clicking a row expands the panel to show raw request and response body text.
- **[Column Header] Latency Tracker**
  - *Default state*: `0ms` (or latency of the most recent query).
  - *Visible location*: Upper-right column header of `Command_Table`.
  - *Observable side effect*: Displays execution durations in milliseconds to pinpoint slower local or cloud models.
- **[Cell] Token Efficiency**
  - *Default state*: `0 tokens` (accumulated).
  - *Visible location*: Inside each query row of `Command_Table`.
  - *Observable side effect*: Details prompt and response token lengths to help optimize prompt templates.

### 6.3 Parity Guard

<!-- Last verified against tag/commit v1.1.165 (commit adb41393) on 2026-06-11 -->

The `parity_guard.py` script serves as the codebase's canonical drift detector, ensuring documentation, Rust routes, environmental variables, and skill manifests remain in absolute alignment.

#### 6.3.1 Invocation Details
Run the verification check via the Python entry point:
```powershell
python execution/parity_guard.py .
```
To run the automated fix (such as synchronizing `API_REFERENCE.md` with modified schemas):
```powershell
python execution/parity_guard.py . FIX=1
```

#### 6.3.2 Failure Modes Detected
The script evaluates and alerts on five specific drift types:
1. **Axum Route Drift**: Flags endpoints defined in `server-rs/src/router.rs` that are missing from `docs/openapi.yaml` (legacy root endpoints trigger warnings, `/v1` endpoints trigger errors).
2. **Environmental Drift**: Flags Rust logic calling `std::env::var("VAR")` that is not declared in `.env.example`.
3. **Manifest Drift**: Validates `data/skills/*.json` manifests to ensure their designated execution scripts exist on disk.
4. **Documentation Drift**: Evaluates `@docs` tags in Rust code. If code changes occur, it requires corresponding markdown file timestamp updates.
5. **API Doc Drift**: Checks if `API_REFERENCE.md` timestamps lag behind `openapi.yaml` modifications.

#### 6.3.3 Exit Code Translation
- **Exit Code 0**: Full alignment. The system has no detected drift.
- **Exit Code 1**: Mismatches detected. Detailed failures are printed to standard output.

> [!NOTE]
> **Parity Verification**: The `parity_guard.py` script does not consume `OPERATIONS_MANUAL.md` directly. It runs independent AST scans against the Rust source directories, OpenAPI files, and environment templates.

### 6.4 Latency Benchmarks & Dual-Trace Analytics (`Benchmark_Analytics`)

The **Performance Analytics Hub** ([Benchmark_Analytics.tsx](file:///d:/TadpoleOS-Dev/src/pages/Benchmark_Analytics.tsx)) provides real-time hardware profiling and execution trace visualization across all autonomous agent nodes in the swarm.

#### 6.4.1 Hardware Latency Benchmarks (`/benchmarks`)
- **Interactive Performance Profiling**: Displays mean execution latencies, P95/P99 distributions, target values, and pass/fail statuses across all registered test categories (`BM-RUN`, `BM-DB`, `BM-RL`, `BM-MCP`, `BM-WS`, `BM-FS`, `BM-HTTP`, `BM-SEC`).
- **On-Demand Execution**: Allows operators to trigger execution profiling with single-click runner buttons (`BM-RUN-01`, `BM-DB-01`, `BM-RL-01`) calling `POST /v1/benchmarks/run/:test_id`.
- **Historical Comparison**: Selecting multiple historical benchmark runs opens a side-by-side variance analysis showing latency deltas and percentage performance shifts.

#### 6.4.2 Dual-Trace Swarm Analytics (`/analytics`)
- **Side-by-Side Telemetry Playback**: Utilizes the `DualTracePlayback` inspector to compare unoptimized linear baseline directives against 100% certified World Model execution state machines.
- **Trace Event Inspection**: Visualizes hypothesis generation, certified backtest parity, discriminative probes, latency variance observations, and execution logs step-by-step.
- **Automated Comparison**: Navigating to `/analytics` automatically selects the latest two benchmark runs for immediate side-by-side inspection.

> [!TIP]
> **Technical Specification**: For Criterion benchmark setups, CLI usage (`cargo bench`), and hardware claim criteria, refer to [Benchmark_Spec.md](./Benchmark_Spec.md).

---

## Appendix A: Daily Operational Workflows

### Example: Running a Private Customer Feedback Analysis
1. **Configure Your Team**: Create a "Support Analyst" using a local model (Ollama + Llama-3-8B) to keep customer data local and private.
2. **Setup the Project Workspace**: Put your customer review spreadsheet (`reviews.csv`) in your designated project folder.
3. **Issue Directive**: Type in the chat: *"Analyze reviews.csv, group them into categories, and write a summary report.txt in the same directory."*
4. **Approve Safe Actions**: Approve the `read_file` request for `reviews.csv` in the Oversight Queue.
5. **Review Draft**: Once completed, review the generated report draft on your Workspaces page and click **Approve** to merge it.

---

## Appendix B: Maintenance & Local Backups

### B.1 Directory Structure & Backups
To protect your configurations, include these folders in your regular office backups:
- **`data/tadpole.db`**: Mapped configurations, agent profiles, and project logs.
- **`data/memory.lance/`**: Local vector databases used for document search. *(Only present when the engine is built with the `vector-memory` feature flag.)*
- **`.env`**: Port definitions and local path configurations (keep private).

### B.2 Automatic Hardware Recovery
If your local computer runs low on GPU memory (VRAM) while loading a local Ollama model, the engine automatically attempts to reload a smaller, quantized fallback model (e.g. `q4_K_M`) to prevent out-of-memory crashes and preserve project progress.

### B.3 Global Environment Variables
Tadpole OS leverages environment variables to manage hardware performance, network bindings, database files, and security policies.

<details>
<summary>🔐 Secrets & Authentication</summary>

- `NEURAL_TOKEN` [RISK: HIGH] — Type: string; Default: `""`. Secret API token required to authenticate all client-dashboard requests.
- `NEURAL_ENGINE_ACCESS_TOKEN` [RISK: HIGH] — Type: string; Default: `""`. Core sidecar access token.
- `AUDIT_PRIVATE_KEY` [RISK: HIGH] — Type: string; Default: `""`. The private key seed used to cryptographically sign transaction logs.
- `WORKFLOW_ENCRYPTION_KEY` [RISK: HIGH] — Type: string; Default: `""`. Encryption key for securing workflow states.
- `CAPABILITY_KEY_CURR` [RISK: HIGH] — Type: string; Default: `""`. Current signing key for client tokens.
- `CAPABILITY_KEY_PREV` [RISK: HIGH] — Type: string; Default: `""`. Previous signing key for client tokens.
- `TEST_PROVIDER_KEY` [RISK: HIGH] — Type: string; Default: `""`. Used in integration tests to bypass API keys.
- `OPENAI_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for OpenAI model querying.
- `GROQ_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for Groq model querying.
- `ANTHROPIC_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for Anthropic model querying.
- `GOOGLE_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for Google Gemini model querying.
- `INCEPTION_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for Inception model querying.
- `DEEPSEEK_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for DeepSeek model querying.
- `REPLICATE_API_KEY` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK API key for Replicate model querying.
- `DISCORD_WEBHOOK` [RISK: HIGH] — Type: string; Default: `""`. ☁️ REQUIRES NETWORK Discord notification webhook url.

</details>

<details>
<summary>🛡️ Security Posture</summary>

- `PRIVACY_MODE` [RISK: HIGH] — Type: boolean; Default: `false`. When true, strictly blocks outbound cloud AI connections.
- `TADPOLE_ALLOW_LOCAL_HTTP` [RISK: HIGH] — Type: boolean; Default: `false`. Bypasses secure HTTPS checks for local development loops.
- `AUTO_APPROVE_SAFE_SKILLS` [RISK: HIGH] — Type: boolean; Default: `true`. Allows safe read-only operations to bypass the Oversight Queue.

</details>

<details>
<summary>🌐 Network & Binding</summary>

- `PORT` [RISK: LOW] — Type: number; Default: `8000`. The HTTP server listen port.
- `BIND_ADDRESS` [RISK: HIGH] — Type: string; Default: `127.0.0.1`. The local loopback IP address of the engine.
- `ALLOWED_ORIGINS` [RISK: HIGH] — Type: string; Default: `http://localhost:5173`. List of permitted browser CORS locations.
- `TRUST_PRIVATE_NETWORKS` [RISK: HIGH] — Type: boolean; Default: `false`. Bypasses proxy verification on local subnet cards.
- `ALLOW_UNSAFE_CORS` [RISK: HIGH] — Type: boolean; Default: `false`. Enables unsafe open CORS profiles.
- `TRUSTED_PROXIES` [RISK: HIGH] — Type: string; Default: `""`. Permitted proxy IP lists.
- `VITE_SYSTEM_BREAKER_FAILURE_THRESHOLD` [RISK: HIGH] — Type: number; Default: `5` (enforced client-side). Maximum consecutive failures allowed before tripping breaker.
- `VITE_SYSTEM_BREAKER_COOLDOWN_MS` [RISK: HIGH] — Type: number; Default: `10000` (enforced client-side). Cooldown time before attempting Half-Open checks.

</details>

<details>
<summary>💾 Persistence & Storage</summary>

- `DATABASE_URL` [RISK: HIGH] — Type: string; Default: `sqlite://data/tadpole.db`. Database connection file path.
- `DATA_DIR` [RISK: MEDIUM] — Type: string; Default: `./data`. Root data storage root path.
- `WORKSPACE_ROOT` [RISK: MEDIUM] — Type: string; Default: `..`. Base sandboxing root path for relative file operations.
- `RESOURCE_ROOT` [RISK: LOW] — Type: string; Default: `./resources`. Storage path for system instructions and graphics.
- `STATIC_DIR` [RISK: MEDIUM] — Type: string; Default: `./static`. Directory path for static frontend assets.

</details>

<details>
<summary>⚙️ Engine Limits</summary>

- `MAX_AGENTS` [RISK: MEDIUM] — Type: number; Default: `100`. The registry limit boundary for maximum concurrent agent identities.
- `MAX_CLUSTERS` [RISK: MEDIUM] — Type: number; Default: `10`. Caps active project directories.
- `MAX_SWARM_DEPTH` [RISK: MEDIUM] — Type: number; Default: `5`. Hard limits recursive agent-spawning depth on local computers.
- `MAX_TASK_LENGTH` [RISK: MEDIUM] — Type: number; Default: `32768`. Caps token consumption boundaries per prompt.
- `ENGINE_RATE_LIMIT` [RISK: MEDIUM] — Type: number; Default: `2000`. Maximum HTTP requests allowed per minute per IP to prevent network overloading.
- `DEFAULT_AGENT_BUDGET_USD` [RISK: MEDIUM] — Type: number; Default: `1.0`. The spending budget limit allocated to new sub-agents.
- `DEFAULT_MISSION_BUDGET_USD` [RISK: MEDIUM] — Type: number; Default: `5.0`. The default spending budget limit allocated to newly created missions.
- `WORKFLOW_CONCURRENCY_LIMIT` [RISK: MEDIUM] — Type: number; Default: `5`. Limits simultaneous execution loops for SOP workflows.
- `WORKFLOW_AGENT_TIMEOUT_SECS` [RISK: MEDIUM] — Type: number; Default: `600`. Time limit for sub-agent executions in workflows.
- `MAX_CONCURRENT_RUNNERS` [RISK: MEDIUM] — Type: number; Default: `10`. Global upper limit across route-started agents and every nested swarm branch; excess branches fail with a retryable capacity response instead of bypassing the operator's resource ceiling.

</details>

<details>
<summary>🤖 Provider Endpoints</summary>

- `OLLAMA_HOST` [RISK: MEDIUM] — Type: string; Default: `http://localhost:11434`. Endpoint address for local model runs.
- `LANCEDB_DEDUPE_THRESHOLD` [RISK: MEDIUM] — Type: number; Default: `0.9`. Similarity score threshold for RAG deduplication.
- `LANCEDB_DRIFT_THRESHOLD` [RISK: MEDIUM] — Type: number; Default: `0.8`. Similarity score threshold for re-indexing triggers.
- `SME_SYNC_INTERVAL_MINS` [RISK: MEDIUM] — Type: number; Default: `30`. Re-indexing interval for background data sync workers.
- `FAILOVER_AMBER_THRESHOLD` [RISK: MEDIUM] — Type: number; Default: `3`. Failure count leading to provider health warning.
- `FAILOVER_RED_THRESHOLD` [RISK: MEDIUM] — Type: number; Default: `5`. Failure count leading to provider offline state.
- `FAILOVER_MAX_ATTEMPTS` [RISK: MEDIUM] — Type: number; Default: `3`. Maximum retry attempts to alternative providers.
- `PROVIDER_TIMEOUT_SECS` [RISK: MEDIUM] — Type: number; Default: `60`. Timeout limit on active model generations.
- `PIPER_MODEL_PATH` [RISK: MEDIUM] — Type: string; Default: `""`. Local path mapping to Piper text-to-speech weights.
- `VAD_MODEL_PATH` [RISK: MEDIUM] — Type: string; Default: `""`. Local path mapping to Silero VAD voice model weights.
- `WHISPER_MODEL_PATH` [RISK: MEDIUM] — Type: string; Default: `""`. Local path mapping to Whisper speech recognition weights.

</details>

<details>
<summary>🔍 Observability & Telemetry</summary>

- `RUST_LOG` [RISK: SAFE] — Type: string; Default: `server_rs=info,tower_http=debug`. Diagnostic logging output levels.
- `DISABLE_TELEMETRY` [RISK: LOW] — Type: boolean; Default: `false`. Stops logging OTel telemetry.
- `HEARTBEAT_INTERVAL_SECS` [RISK: LOW] — Type: number; Default: `30`. Hearts update ticks.

</details>

<details>
<summary>🛠️ Dev / Test / CI</summary>

- `BUNKER_NODES` [RISK: HIGH] — Type: string; Default: `bunker-1:Swarm Bunker 1:localhost`. Node identification lists formatted as `<id>:<display_name>:<host>` tuples, comma-separated for multiple entries.
- `TADPOLE_NULL_PROVIDERS` [RISK: MEDIUM] — Type: boolean; Default: `false`. Mocks LLM responses for CI/testing.
- `LEGACY_JSON_BACKUP` [RISK: MEDIUM] — Type: boolean; Default: `false`. Keeps old JSON backup files active.
- `SKIP_DB_SEED` [RISK: MEDIUM] — Type: boolean; Default: `false`. Skip database default seeding.
- `CLUSTER_ID` [RISK: LOW] — Type: string; Default: `local-1`. Unique identifier tag for the local node.
- `KUBERNETES_SERVICE_HOST` [RISK: LOW] — Type: string; Default: `""`. Automatically loaded host address within cluster environments.

</details>

### B.4 Build Feature Flags
Tadpole OS provides compilation flags that allow optimizing VRAM footprint on office computers.

- `vector-memory` [RISK: MEDIUM] — Compiles LanceDB and Apache Arrow libraries into the server to enable persistent semantic memory indexing. Stores vectors locally inside `data/memory.lance/`. Disabled by default for simplified installation on Windows office nodes.
- `neural-audio` [RISK: MEDIUM] — Integrates the ONNX runtime (`ort`), Whisper speech-to-text, and audio utilities to support real-time voice streaming. Disabled by default on legacy CPUs.

---

[//]: # (Metadata: [OPERATIONS_MANUAL])
<!-- Last verified against tag/commit v1.1.165 (commit adb41393) on 2026-06-11 -->
