ENGINE: Added File Headers and Guidance in AGENTS.md

AGENTS.md

@@ -5,6 +5,21 @@
 The `script_engines.py` helper exposes a PowerShell runner for potential server-side orchestration, but no current Flask route invokes it; agent-side script execution lives under the roles in `Data/Agent`.
 - Agents run inside the packaged Python venv (`Data/Agent` mirrored to `Agent/`). `agent.py` handles the primary connection and hot-loads roles from `Data/Agent/Roles` at agent startup.
 
+## Engine File Headers (Codex Agent Guidance)
+- Any new Python modules created under `Data/Engine` or its staging counterpart `Engine/Data/Engine` must begin with the standardized commentary header that documents file purpose and API coverage.
+- Mirror the exact formatting shown below, updating the file path, description, and endpoint list to match the new module. If the file does not expose API routes, set the section to `API Endpoints (if applicable): None`.
+  ```text
+  # ======================================================
+  # 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.
+  # ======================================================
+  ```
+- Always adjust the first line after `# Description:` and each endpoint bullet so operators can quickly understand why the file exists and how to authenticate to any routes.
+- When modifying an existing module that is missing this header, add it as part of the change before proceeding with further edits.
+
 ## Logging Policy (Centralized, Rotated)
 - **Log Locations**
   - Agent: `<ProjectRoot>/Logs/Agent/<service>.log`
@@ -118,4 +133,4 @@ Important: The Ansible integration is not production‑ready. Do not rely on it
   - Database‑fed credential management (per device/site/global), stored securely and surfaced to playbook runs.
   - First‑class selection of connection types (local | PSRP | WinRM) from the UI and scheduler, with per‑run credential binding.
   - Reliable live output and cancel semantics; hardened recap ingestion and history.
-  - Verified packaging of required Ansible components and Windows collections inside the agent venv.
+  - Verified packaging of required Ansible components and Windows collections inside the agent venv.

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