WIP: docs/ restructuring

Author: vredchenko

docs/reference/cli-reference.md docs/agent/cli-reference.mddocs/reference/cli-reference.md renamed to docs/agent/cli-reference.md

@@ -480,4 +480,4 @@ The watch command requires a compatible SmartEM backend API with the following e
 - Consider `--heartbeat-interval` tuning based on network stability
 - Use `--dry-run` for local testing and development
 
-This CLI reference provides comprehensive coverage of all SmartEM Agent command-line functionality. For additional help with specific use cases or troubleshooting, refer to the [CLI Troubleshooting Guide](troubleshoot-cli.md).
+This CLI reference provides comprehensive coverage of all SmartEM Agent command-line functionality. For additional help with specific use cases or troubleshooting, refer to the [CLI Troubleshooting Guide](troubleshooting.md).

docs/how-to/run-agent.md docs/agent/deployment.mddocs/how-to/run-agent.md renamed to docs/agent/deployment.md

@@ -27,7 +27,7 @@ The agent operates in several modes depending on the timing of EPU data acquisit
 
 ## Quick Start
 
-For comprehensive parameter documentation, see the [CLI Reference](../reference/cli-reference.md). For troubleshooting, see the [CLI Troubleshooting Guide](troubleshoot-cli.md).
+For comprehensive parameter documentation, see the [CLI Reference](cli-reference.md). For troubleshooting, see the [CLI Troubleshooting Guide](troubleshooting.md).
 
 ### Basic Directory Monitoring
 

docs/agent/index.md

@@ -0,0 +1,22 @@
+# Agent
+
+Documentation for the SmartEM Agent - the EPU filesystem watcher that runs on Windows workstations near the microscope.
+
+```{toctree}
+:maxdepth: 1
+
+cli-reference
+deployment
+troubleshooting
+```
+
+## Topics
+
+### Usage
+
+- [CLI Reference](cli-reference.md) - Command-line interface documentation and options
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+
+### Deployment
+
+- [Agent Deployment](deployment.md) - Running the agent on Windows workstations

docs/how-to/troubleshoot-cli.md docs/agent/troubleshooting.mddocs/how-to/troubleshoot-cli.md renamed to docs/agent/troubleshooting.md

@@ -1,6 +1,6 @@
 # SmartEM CLI Troubleshooting Guide
 
-This guide provides solutions for common issues encountered when using the SmartEM Agent command-line interface. For comprehensive parameter documentation, see the [CLI Reference](../reference/cli-reference.md).
+This guide provides solutions for common issues encountered when using the SmartEM Agent command-line interface. For comprehensive parameter documentation, see the [CLI Reference](cli-reference.md).
 
 ## Quick Diagnostics
 

docs/architecture/index.md

@@ -0,0 +1,18 @@
+# Architecture
+
+System design documentation and architectural decision records.
+
+## Decision Records
+
+Architectural Decision Records (ADRs) document significant technical decisions.
+
+- [Decision Records](../decision-records/index.md) - Browse all ADRs
+
+## System Design
+
+Architecture documentation is maintained in the main smartem-decisions repository:
+
+- System overview and component interactions
+- Backend-Agent communication protocols (SSE, REST)
+- Data flow and message queue patterns
+- Database schema design

docs/athena/index.md

@@ -0,0 +1,30 @@
+# Athena Integration
+
+Documentation for ThermoFisher Athena API integration.
+
+## API Reference
+
+The Athena Decision Service API specification is available in the API documentation:
+
+- [Athena API Docs](../api/athena/index.html) - Interactive Swagger UI
+- [API Documentation Guide](../backend/api-documentation.md) - How to use the interactive documentation
+
+## Mock Server
+
+For local development without access to a real Athena service:
+
+```bash
+# Install mock dependencies
+pip install -e ".[mock]"
+
+# Start the Athena mock server
+python -c "
+from athena_api.mock import AthenaAPIServer
+server = AthenaAPIServer()
+server.run()
+"
+
+# Visit http://localhost:8000/docs
+```
+
+See the [API Documentation](../backend/api-documentation.md#mock-server-for-development) guide for more details.

docs/how-to/use-api-documentation.md docs/backend/api-documentation.mddocs/how-to/use-api-documentation.md renamed to docs/backend/api-documentation.md

@@ -10,10 +10,10 @@ The core backend service providing HTTP API, database operations, and message qu
 
 # launch RabbitMQ worker (consumer)
 python -m smartem_backend.consumer              # ERROR level (default)
-python -m smartem_backend.consumer -v           # INFO level  
+python -m smartem_backend.consumer -v           # INFO level
 python -m smartem_backend.consumer -vv          # DEBUG level
 
-# simulating an system event: 
+# simulating an system event:
 python -m smartem_backend.simulate_msg --help # to see a list of options
 ./tools/simulate-messages.sh # run a simulation, triggering system events in sequence
 

docs/how-to/run-backend.md docs/backend/api-server.mddocs/how-to/run-backend.md renamed to docs/backend/api-server.md

@@ -140,7 +140,7 @@ def upgrade() -> None:
         column('preference_key', sa.String),
         column('preference_value', sa.JSON)
     )
-    
+
     op.bulk_insert(user_preferences, [
         {
             'user_id': 'system',