ENGINE: Added File Headers and Guidance in AGENTS.md

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."