ENGINE: Added File Headers and Guidance in AGENTS.md

Data/Engine/Unit_Tests/__init__.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\Unit_Tests\__init__.py
+# Description: Package marker for Engine unit and smoke tests.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Unit and smoke tests for the Borealis Engine runtime."""

Data/Engine/Unit_Tests/conftest.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\Unit_Tests\conftest.py
+# Description: Pytest fixtures that seed the Engine app, SQLite schema, TLS materials, and WebUI assets.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 from __future__ import annotations
 
 import json

Data/Engine/Unit_Tests/test_core_api.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\Unit_Tests\test_core_api.py
+# Description: Validates the Engine /health endpoint wiring.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 from __future__ import annotations
 
 

Data/Engine/Unit_Tests/test_devices_api.py

@@ -1,3 +1,9 @@
+# ======================================================
+# Data\Engine\Unit_Tests\test_devices_api.py
+# Description: Exercises device management endpoints covering lists, views, site workflows, and approvals.
+#
+# API Endpoints (if applicable): None
+# ======================================================
 
 from __future__ import annotations
 

Data/Engine/Unit_Tests/test_enrollment_api.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\Unit_Tests\test_enrollment_api.py
+# Description: Covers device enrollment request and poll flows including cryptographic proof handling.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 from __future__ import annotations
 
 import base64

Data/Engine/Unit_Tests/test_tokens_api.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\Unit_Tests\test_tokens_api.py
+# Description: Validates refresh token issuance, expiry handling, and error cases.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 from __future__ import annotations
 
 import hashlib

Data/Engine/Unit_Tests/test_web_ui.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\Unit_Tests\test_web_ui.py
+# Description: Ensures Engine WebUI static routing and SPA fallback respond as expected.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 from __future__ import annotations
 
 

Data/Engine/__init__.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\__init__.py
+# Description: Package initializer exposing create_app and EngineContext for the Borealis Engine.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Borealis Engine runtime package.
 
 This package houses the next-generation server runtime that will gradually

Data/Engine/bootstrapper.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\bootstrapper.py
+# Description: Bootstrap utility that resolves runtime config, stages WebUI assets, provisions TLS, and starts the Engine Socket.IO server.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Entrypoint helpers for running the Borealis Engine runtime.
 
 The bootstrapper assembles configuration via :func:`Data.Engine.config.load_runtime_config`

Data/Engine/config.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\config.py
+# Description: Configuration loader aligning the Engine runtime with legacy defaults, logging policy, and TLS discovery.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Configuration helpers for the Borealis Engine runtime.
 
 Stage 2 of the migration focuses on lifting the legacy configuration loading

Data/Engine/server.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\server.py
+# Description: Flask/Socket.IO application factory wiring Engine services, logging, and legacy bridge registration.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Stage 2 Borealis Engine application factory.
 
 Stage 1 introduced the structural skeleton for the Engine runtime.  Stage 2

Data/Engine/services/API/__init__.py

@@ -1,3 +1,11 @@
+# ======================================================
+# Data\Engine\services\API\__init__.py
+# Description: Registers Engine API groups and bridges to legacy modules while exposing core utility routes.
+#
+# API Endpoints (if applicable):
+# - GET /health (No Authentication) - Returns an OK status for liveness probing.
+# ======================================================
+
 """API service adapters for the Borealis Engine runtime."""
 from __future__ import annotations
 

Data/Engine/services/API/access_management/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\access_management\__init__.py
+# Description: Namespace for access-management endpoints consumed by the Engine auth group.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/access_management/credentials.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\access_management\credentials.py
+# Description: Placeholder for future credential management endpoints (not yet implemented).
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Placeholder for credentials API module."""

Data/Engine/services/API/access_management/login.py

@@ -1,3 +1,14 @@
+# ======================================================
+# Data\Engine\services\API\access_management\login.py
+# Description: Primary authentication blueprint used by the Engine auth group for sessions, MFA, and logout.
+#
+# API Endpoints (if applicable):
+# - POST /api/auth/login (No Authentication) - Authenticates operator credentials and starts a session token.
+# - POST /api/auth/logout (Token Authenticated) - Clears the active operator session and authentication cookie.
+# - POST /api/auth/mfa/verify (Token Authenticated (MFA pending)) - Verifies TOTP codes during multifactor setup or login.
+# - GET /api/auth/me (Token Authenticated) - Returns the currently authenticated operator profile.
+# ======================================================
+
 """Authentication endpoints for the Borealis Engine API."""
 from __future__ import annotations
 

Data/Engine/services/API/access_management/security/tokens.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\access_management\security\tokens.py
+# Description: Placeholder for token lifecycle endpoints within access management.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Placeholder for tokens API module."""

Data/Engine/services/API/access_management/users.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\access_management\users.py
+# Description: Placeholder for operator user management endpoints (not yet implemented).
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Placeholder for users API module."""

Data/Engine/services/API/assemblies/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\assemblies\__init__.py
+# Description: Namespace for assembly orchestration API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/assemblies/management.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\assemblies\management.py
+# Description: Placeholder for assembly management endpoints (work in progress).
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module assemblies/management.py."

Data/Engine/services/API/authentication.py

@@ -1,3 +1,14 @@
+# ======================================================
+# Data\Engine\services\API\authentication.py
+# Description: Legacy authentication blueprint implementing username/password login, logout, MFA, and profile discovery.
+#
+# API Endpoints (if applicable):
+# - POST /api/auth/login (No Authentication) - Authenticates operator credentials and starts a session token.
+# - POST /api/auth/logout (Token Authenticated) - Clears the active operator session and authentication cookie.
+# - POST /api/auth/mfa/verify (Token Authenticated (MFA pending)) - Verifies TOTP codes during multifactor setup or login.
+# - GET /api/auth/me (Token Authenticated) - Returns the currently authenticated operator profile.
+# ======================================================
+
 """Authentication endpoints for the Borealis Engine API."""
 from __future__ import annotations
 

Data/Engine/services/API/devices/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\devices\__init__.py
+# Description: Namespace aggregator for device-related API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/devices/approval.py

@@ -1,3 +1,16 @@
+# ======================================================
+# Data\Engine\services\API\devices\approval.py
+# Description: Administrative device enrollment endpoints covering code lifecycle and approval queue actions.
+#
+# API Endpoints (if applicable):
+# - GET /api/admin/enrollment-codes (Token Authenticated (Admin)) - Lists enrollment/install codes with optional status filtering.
+# - POST /api/admin/enrollment-codes (Token Authenticated (Admin)) - Creates a new enrollment/install code with TTL and usage limits.
+# - DELETE /api/admin/enrollment-codes/<code_id> (Token Authenticated (Admin)) - Deletes an enrollment/install code record.
+# - GET /api/admin/device-approvals (Token Authenticated (Admin)) - Enumerates pending and historical device approval records.
+# - POST /api/admin/device-approvals/<approval_id>/approve (Token Authenticated (Admin)) - Approves a pending device and handles hostname conflicts.
+# - POST /api/admin/device-approvals/<approval_id>/deny (Token Authenticated (Admin)) - Denies a pending device approval request.
+# ======================================================
+
 """Admin-focused device enrollment and approval endpoints."""
 from __future__ import annotations
 

Data/Engine/services/API/devices/enrollment.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\devices\enrollment.py
+# Description: Placeholder for device enrollment API bridge (not yet implemented).
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module devices/enrollment.py."

Data/Engine/services/API/devices/management.py

@@ -1,3 +1,27 @@
+# ======================================================
+# Data\Engine\services\API\devices\management.py
+# Description: Device inventory, list view, site management, and repository hash endpoints for the Engine API transition layer.
+#
+# API Endpoints (if applicable):
+# - POST /api/agent/details (Device Authenticated) - Ingests hardware and inventory payloads from enrolled agents.
+# - GET /api/devices (No Authentication) - Returns a summary list of known devices for the WebUI transition.
+# - GET /api/devices/<guid> (No Authentication) - Retrieves a single device record by GUID, including summary fields.
+# - GET /api/device/details/<hostname> (No Authentication) - Returns full device details keyed by hostname.
+# - POST /api/device/description/<hostname> (Token Authenticated) - Updates the human-readable description for a device.
+# - GET /api/device_list_views (No Authentication) - Lists saved device table view definitions.
+# - GET /api/device_list_views/<int:view_id> (No Authentication) - Retrieves a specific saved device table view definition.
+# - POST /api/device_list_views (Token Authenticated) - Creates a custom device list view for the signed-in operator.
+# - PUT /api/device_list_views/<int:view_id> (Token Authenticated) - Updates an existing device list view definition.
+# - DELETE /api/device_list_views/<int:view_id> (Token Authenticated) - Deletes a saved device list view.
+# - GET /api/sites (No Authentication) - Lists known sites and their summary metadata.
+# - POST /api/sites (Token Authenticated (Admin)) - Creates a new site for grouping devices.
+# - POST /api/sites/delete (Token Authenticated (Admin)) - Deletes one or more sites by identifier.
+# - GET /api/sites/device_map (No Authentication) - Provides hostname to site assignment mapping data.
+# - POST /api/sites/assign (Token Authenticated (Admin)) - Assigns a set of devices to a given site.
+# - POST /api/sites/rename (Token Authenticated (Admin)) - Renames an existing site record.
+# - GET /api/repo/current_hash (No Authentication) - Fetches the current agent repository hash (with caching).
+# - GET /api/agent/hash_list (Loopback Restricted) - Returns stored agent hash metadata for localhost diagnostics.
+# ======================================================
 
 """Device management endpoints for the Borealis Engine API."""
 from __future__ import annotations

Data/Engine/services/API/devices/remote_control.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\devices\remote_control.py
+# Description: Placeholder for remote control and live session endpoints.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module devices/remote_control.py."

Data/Engine/services/API/filters/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\filters\__init__.py
+# Description: Namespace for saved filter API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/filters/management.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\filters\management.py
+# Description: Placeholder for filter management endpoints.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module filters/management.py."

Data/Engine/services/API/scheduled_jobs/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\scheduled_jobs\__init__.py
+# Description: Namespace for scheduled job API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/scheduled_jobs/management.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\scheduled_jobs\management.py
+# Description: Placeholder for scheduled job management endpoints.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module scheduled_jobs/management.py."

Data/Engine/services/API/scheduled_jobs/runner.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\scheduled_jobs\runner.py
+# Description: Placeholder for scheduled job runner control endpoints.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module scheduled_jobs/runner.py."

Data/Engine/services/API/server/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\server\__init__.py
+# Description: Namespace for server information and admin API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/server/info.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\server\info.py
+# Description: Placeholder for server information endpoints.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module server/info.py."

Data/Engine/services/API/sites/__init__.py

@@ -0,0 +1,7 @@
+# ======================================================
+# Data\Engine\services\API\sites\__init__.py
+# Description: Namespace aggregator for site management API modules.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+

Data/Engine/services/API/sites/management.py

@@ -1 +1,8 @@
+# ======================================================
+# Data\Engine\services\API\sites\management.py
+# Description: Placeholder for dedicated site management endpoints (current logic lives under devices.management).
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 "Placeholder for API module sites/management.py."

Data/Engine/services/WebSocket/__init__.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\services\WebSocket\__init__.py
+# Description: Placeholder hook for registering Engine Socket.IO namespaces.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """WebSocket service stubs for the Borealis Engine runtime.
 
 Future stages will move Socket.IO namespaces and event handlers here. Stage 1

Data/Engine/services/WebUI/__init__.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\services\WebUI\__init__.py
+# Description: Registers the SPA static asset blueprint and 404 fallback for the Engine WebUI.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """WebUI static asset handling for the Borealis Engine runtime."""
 from __future__ import annotations
 

Data/Engine/services/__init__.py

@@ -1,3 +1,10 @@
+# ======================================================
+# Data\Engine\services\__init__.py
+# Description: Aggregates API, WebSocket, and WebUI service registration helpers for the Engine runtime.
+#
+# API Endpoints (if applicable): None
+# ======================================================
+
 """Service registration hooks for the Borealis Engine runtime."""
 
 from . import API, WebSocket, WebUI