diff --git a/.clinerules b/.clinerules
new file mode 100644
index 0000000..8e80418
--- /dev/null
+++ b/.clinerules
@@ -0,0 +1,6 @@
+# POINTER FILE — single source of truth is /AGENTS.md at the repo root.
+# Edit AGENTS.md, not this file.
+
+Follow the project guidelines defined in the root AGENTS.md file:
+stack, commands, code style, architecture, testing, Raspberry Pi
+constraints, security, and git conventions are all defined there.
diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc
new file mode 100644
index 0000000..f758ce7
--- /dev/null
+++ b/.cursor/rules/project.mdc
@@ -0,0 +1,9 @@
+---
+description: Project guidelines — single source of truth is /AGENTS.md
+alwaysApply: true
+---
+
+Follow the project guidelines defined in the root AGENTS.md file:
+stack, commands, code style, architecture, testing, Raspberry Pi
+constraints, security, and git conventions are all defined there.
+Edit AGENTS.md, not this file.
diff --git a/.cursorrules b/.cursorrules
index 4a036f5..8e80418 100644
--- a/.cursorrules
+++ b/.cursorrules
@@ -1,317 +1,6 @@
-# Minecraft Server Management - Agent Instructions
+# POINTER FILE — single source of truth is /AGENTS.md at the repo root.
+# Edit AGENTS.md, not this file.
-## Project Overview
-
-This is a Minecraft server management system optimized for Raspberry Pi 5 (ARM64), providing Docker-based deployment, automated backups, plugin management, multi-world support, REST API, and a React web interface.
-
-## Architecture
-
-### Technology Stack
-
-- **Backend API**: Python 3 with Flask (REST API for server management)
-- **Frontend**: React with Vite, Tailwind CSS
-- **Server Management**: Bash scripts for server operations
-- **Containerization**: Docker & Docker Compose
-- **Target Platform**: Raspberry Pi 5 (ARM64), but supports x86_64
-- **Testing**: pytest for Python, Vitest for React, BATS for shell scripts
-
-### Project Structure
-
-```
-minecraft/
-├── api/ # Python Flask REST API
-│ ├── server.py # Main API server
-│ └── requirements.txt # Python dependencies
-├── web/ # React frontend
-│ ├── src/ # React source code
-│ └── package.json # Node dependencies
-├── scripts/ # Shell scripts for server management
-│ ├── manage.sh # Main management script
-│ ├── backup-scheduler.sh
-│ ├── plugin-manager.sh
-│ └── ...
-├── config/ # Configuration files
-│ ├── api.conf # API configuration
-│ └── *.conf # Various config files
-├── docs/ # Documentation
-├── tests/ # Test suites
-│ ├── api/ # Python API tests
-│ ├── integration/ # Integration tests
-│ └── unit/ # Unit tests
-├── docker-compose.yml # Docker Compose configuration
-├── Dockerfile # Docker image definition
-├── Makefile # Convenience commands
-└── README.md # Main documentation
-```
-
-## Code Standards
-
-### Shell Scripts
-
-- **Shebang**: Always use `#!/bin/bash`
-- **Error Handling**: Use `set -e` at the start
-- **Indentation**: 4 spaces (not tabs)
-- **Variables**: Always quote variables: `"$VAR"` not `$VAR`
-- **Functions**: Use functions for repeated code
-- **Colors**: Use ANSI color codes for output (RED, GREEN, YELLOW, BLUE, NC)
-- **Comments**: Add comments for complex logic
-- **Syntax Check**: Run `bash -n script.sh` before committing
-
-Example:
-
-```bash
-#!/bin/bash
-set -e
-
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-NC='\033[0m'
-
-function example_function() {
- local param="$1"
- echo -e "${GREEN}Processing: $param${NC}"
-}
-```
-
-### Python Code
-
-- **Style**: Follow PEP 8
-- **Type Hints**: Use type hints where appropriate
-- **Docstrings**: Include docstrings for functions and classes
-- **Error Handling**: Use try/except with specific exceptions
-- **Imports**: Group imports (stdlib, third-party, local)
-- **Path Handling**: Use `pathlib.Path` for file paths
-
-Example:
-
-```python
-from pathlib import Path
-from typing import Optional
-
-def example_function(param: str) -> Optional[Path]:
- """Process parameter and return path."""
- try:
- path = Path(param)
- return path if path.exists() else None
- except Exception as e:
- print(f"Error: {e}")
- return None
-```
-
-### React/JavaScript
-
-- **Framework**: React with functional components and hooks
-- **Styling**: Tailwind CSS for styling
-- **Testing**: Vitest for unit tests
-- **API Calls**: Use services/api.js for API communication
-- **Components**: Keep components small and focused
-- **State Management**: Use React hooks (useState, useEffect)
-
-### Docker
-
-- **Base Images**: Use official images when possible
-- **Multi-stage**: Use multi-stage builds for optimization
-- **Layers**: Minimize layers, clean up in same layer
-- **Environment Variables**: Use .env files and docker-compose.yml
-- **Health Checks**: Include healthcheck in docker-compose.yml
-
-### YAML Files
-
-- **Indentation**: 2 spaces
-- **Environment Variables**: Use `${VAR:-default}` syntax
-- **Validation**: Run `docker-compose config` to validate
-
-## Development Workflow
-
-### Making Changes
-
-1. Create feature branch: `git checkout -b feature/feature-name`
-2. Make changes following code standards
-3. Test changes thoroughly
-4. Update documentation if needed
-5. Commit with clear messages: `git commit -m "Add feature: description"`
-6. Push and create PR
-
-### Testing Requirements
-
-- **Shell Scripts**: Run `bash -n script.sh` for syntax check
-- **Python**: Run `pytest tests/api/ -v` for API tests
-- **React**: Run `npm test` for frontend tests
-- **Docker**: Run `docker-compose config` to validate
-- **Integration**: Test on Raspberry Pi 5 when possible
-
-### Documentation
-
-- **Update README.md** for user-facing changes
-- **Update relevant docs/** files for feature changes
-- **Update CHANGELOG.md** for all changes
-- **Add examples** to CONFIGURATION_EXAMPLES.md when adding config options
-- **Update QUICK_REFERENCE.md** when adding commands
-
-## Important Considerations
-
-### Raspberry Pi 5 Optimization
-
-- **Memory**: Be mindful of memory constraints (4GB/8GB models)
-- **CPU**: ARM64 architecture, optimize for efficiency
-- **Storage**: Consider SD card write limits
-- **Performance**: Test on actual hardware when possible
-
-### Docker Best Practices
-
-- **Resource Limits**: Set appropriate memory limits in docker-compose.yml
-- **Volumes**: Use named volumes or bind mounts appropriately
-- **Networking**: Use custom networks for isolation
-- **Logging**: Configure log rotation to prevent disk fill
-
-### Security
-
-- **API Keys**: Store in config/api-keys.json, never commit secrets
-- **RCON**: Use secure passwords, generate randomly
-- **File Permissions**: Ensure proper permissions on scripts and configs
-- **Input Validation**: Validate all user inputs in API
-
-### Error Handling
-
-- **Graceful Degradation**: Handle missing dependencies gracefully
-- **User Feedback**: Provide clear error messages
-- **Logging**: Log errors with context
-- **Recovery**: Implement rollback mechanisms where appropriate
-
-## Common Patterns
-
-### Script Structure
-
-```bash
-#!/bin/bash
-set -e
-
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-NC='\033[0m'
-
-# Script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Functions
-function main_function() {
- # Implementation
-}
-
-# Main execution
-if [ "$#" -eq 0 ]; then
- usage
- exit 1
-fi
-
-case "$1" in
- command)
- main_function
- ;;
- *)
- usage
- exit 1
- ;;
-esac
-```
-
-### API Endpoint Pattern
-
-```python
-@app.route('/api/endpoint', methods=['GET'])
-@require_api_key
-def endpoint():
- """Endpoint description."""
- try:
- # Implementation
- return jsonify({"status": "success", "data": result})
- except Exception as e:
- return jsonify({"status": "error", "message": str(e)}), 500
-```
-
-### React Component Pattern
-
-```jsx
-import { useState, useEffect } from 'react';
-import { api } from '../services/api';
-
-export function Component() {
- const [data, setData] = useState(null);
-
- useEffect(() => {
- api.getData().then(setData);
- }, []);
-
- return
{/* Component JSX */}
;
-}
-```
-
-## File Naming Conventions
-
-- **Scripts**: `kebab-case.sh` (e.g., `backup-scheduler.sh`)
-- **Python**: `snake_case.py` (e.g., `server.py`)
-- **React**: `PascalCase.jsx` for components (e.g., `StatusCard.jsx`)
-- **Config**: `kebab-case.conf` (e.g., `backup-schedule.conf`)
-- **Documentation**: `UPPERCASE.md` (e.g., `README.md`)
-
-## Testing Standards
-
-- **Unit Tests**: Test individual functions/components
-- **Integration Tests**: Test script interactions
-- **API Tests**: Test all endpoints with pytest
-- **Coverage**: Aim for >50% coverage (currently at 51%)
-- **Test Files**: Mirror source structure in `tests/` directory
-
-## Documentation Standards
-
-- **Markdown**: Use Markdown for all documentation
-- **Code Examples**: Include working code examples
-- **Links**: Keep internal links relative
-- **Structure**: Use clear headings and sections
-- **Updates**: Update docs when making changes
-
-## Git Workflow
-
-- **Branches**: Use `feature/`, `fix/`, `docs/` prefixes
-- **Commits**: Clear, descriptive commit messages
-- **PRs**: One feature/fix per PR
-- **Reviews**: Address feedback before merging
-
-## When Adding New Features
-
-1. **Check TASKS.md** for related tasks
-2. **Follow existing patterns** in similar features
-3. **Add tests** for new functionality
-4. **Update documentation** (README, relevant docs/)
-5. **Update CHANGELOG.md** with changes
-6. **Test on Raspberry Pi 5** if hardware-specific
-
-## Common Commands
-
-- `./manage.sh start` - Start server
-- `./manage.sh stop` - Stop server
-- `make test` - Run tests
-- `make build` - Build Docker image
-- `docker-compose logs` - View logs
-- `pytest tests/api/ -v` - Run API tests
-
-## Key Files to Know
-
-- `scripts/manage.sh` - Main management script
-- `api/server.py` - REST API server
-- `docker-compose.yml` - Docker configuration
-- `README.md` - Main documentation
-- `TASKS.md` - Development tasks
-- `CONTRIBUTING.md` - Contribution guidelines
-
-## Remember
-
-- Always test on Raspberry Pi 5 when possible
-- Keep memory usage in mind (4GB/8GB models)
-- Follow existing code patterns
-- Update documentation with changes
-- Write tests for new features
-- Use clear, descriptive names
-- Handle errors gracefully
-- Provide user feedback
+Follow the project guidelines defined in the root AGENTS.md file:
+stack, commands, code style, architecture, testing, Raspberry Pi
+constraints, security, and git conventions are all defined there.
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..d55dee7
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,24 @@
+# Copy to .env and adjust. Docker Compose reads .env automatically; .env itself is
+# gitignored. Every value below is optional — the defaults shown are what
+# docker-compose.yml falls back to.
+
+# --- Minecraft server ------------------------------------------------------
+MINECRAFT_VERSION=1.20.4
+# vanilla | paper | fabric -- these are what scripts/download-server.sh can
+# fetch. "spigot" is recognised but exits with a pointer to BuildTools, which
+# you must run yourself; Forge/Quilt servers are detected by
+# scripts/mod-loader-detector.sh once installed, but are not downloaded here.
+SERVER_TYPE=vanilla
+SERVER_PORT=25565
+EULA=TRUE # you must accept https://www.minecraft.net/eula
+TZ=UTC
+
+# --- Memory ----------------------------------------------------------------
+# 4GB Pi 5: MEMORY_MIN=1G MEMORY_MAX=2G CONTAINER_MEMORY_LIMIT=3G
+# 8GB Pi 5: MEMORY_MIN=2G MEMORY_MAX=4G CONTAINER_MEMORY_LIMIT=5G
+#
+# CONTAINER_MEMORY_LIMIT must exceed MEMORY_MAX by roughly 0.5-1G: the JVM needs
+# headroom beyond the heap. Setting it equal to MEMORY_MAX causes a restart loop.
+MEMORY_MIN=1G
+MEMORY_MAX=2G
+CONTAINER_MEMORY_LIMIT=3G
diff --git a/.eslintignore b/.eslintignore
deleted file mode 100644
index 80b63c5..0000000
--- a/.eslintignore
+++ /dev/null
@@ -1,8 +0,0 @@
-node_modules/
-dist/
-build/
-coverage/
-*.config.js
-vite.config.js
-vitest.config.js
-
diff --git a/.eslintrc.json b/.eslintrc.json
deleted file mode 100644
index 958aa9d..0000000
--- a/.eslintrc.json
+++ /dev/null
@@ -1,37 +0,0 @@
-{
- "env": {
- "browser": true,
- "es2021": true,
- "node": true
- },
- "extends": [
- "eslint:recommended",
- "plugin:react/recommended",
- "plugin:react-hooks/recommended"
- ],
- "parserOptions": {
- "ecmaVersion": "latest",
- "sourceType": "module",
- "ecmaFeatures": {
- "jsx": true
- }
- },
- "plugins": ["react", "react-hooks", "react-refresh"],
- "rules": {
- "react/react-in-jsx-scope": "off",
- "react/prop-types": "warn",
- "react-hooks/rules-of-hooks": "error",
- "react-hooks/exhaustive-deps": "warn",
- "react-refresh/only-export-components": [
- "warn",
- { "allowConstantExport": true }
- ],
- "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
- "no-console": ["warn", { "allow": ["warn", "error"] }]
- },
- "settings": {
- "react": {
- "version": "detect"
- }
- }
-}
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..dfb9881
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,13 @@
+# Project Guidelines
+
+
+
+Follow the instructions in the root `AGENTS.md` file: stack, commands, code style,
+architecture, testing, Raspberry Pi constraints, security, and git conventions are
+all defined there.
+
+Copilot-specific additions only below this line.
diff --git a/.gitignore b/.gitignore
index fc29b0b..e40552c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,8 +6,10 @@ plugins/
# Configuration files with secrets
.env
config/*.conf
+config/*.json
+config/audit.log
!config/README.md
-!config/examples/
+!config/*.conf.example
# Temporary files
*.log
@@ -32,7 +34,8 @@ docker-volumes/
# Build artifacts
*.jar
-!server.jar # Keep server.jar if manually placed
+# Keep server.jar if it is manually placed
+!server.jar
# Python (if using pre-commit)
__pycache__/
@@ -52,13 +55,21 @@ yarn-error.log*
out/
dist/
-# Test coverage (generated by pytest --cov)
+# Test coverage and tooling caches (generated)
.coverage
htmlcov/
coverage.json
coverage.xml
coverage-gaps.txt
.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Playwright (generated)
+playwright-report/
+test-results/
+blob-report/
+playwright/.cache/
# Local development
.local/
diff --git a/.windsurfrules b/.windsurfrules
new file mode 100644
index 0000000..8e80418
--- /dev/null
+++ b/.windsurfrules
@@ -0,0 +1,6 @@
+# POINTER FILE — single source of truth is /AGENTS.md at the repo root.
+# Edit AGENTS.md, not this file.
+
+Follow the project guidelines defined in the root AGENTS.md file:
+stack, commands, code style, architecture, testing, Raspberry Pi
+constraints, security, and git conventions are all defined there.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..db765ed
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,209 @@
+# Project Guidelines (AGENTS.md)
+
+
+
+## Project Overview
+
+A Minecraft server management system for **Raspberry Pi 5 (ARM64)**, also usable on
+x86_64. It provides Docker-based deployment, automated and cloud backups, plugin and
+mod management, multi-world support, RCON, log management, analytics, a Flask REST
+API, and a React web admin panel.
+
+## Stack
+
+| Layer | Technology |
+| --- | --- |
+| Server management | Bash scripts in `scripts/`, shared helpers in `scripts/lib/common.sh` |
+| REST API | Python 3.11+ / Flask (`api/server.py`) |
+| Web admin panel | React 18 + Vite + Tailwind CSS (`web/`) |
+| Containers | Docker + Docker Compose v2 |
+| Service management | systemd units in `systemd/` |
+| Tests | pytest (API), Vitest (React), Playwright (browser E2E), BATS (shell) |
+| Package manager | **npm** (this repo is not on pnpm) |
+
+## Repository Layout
+
+```
+api/ Flask REST API (server.py, security.py) + OpenAPI spec in api/openapi.yaml
+web/ React admin panel; its own package.json, ESLint, Vite and Playwright configs
+scripts/ Bash management scripts; scripts/lib/common.sh holds shared helpers
+config/ Runtime config; only *.example files are committed (real .conf files are gitignored)
+systemd/ Unit and timer files for the Pi
+tests/ api/ (pytest), unit/ integration/ e2e/ (BATS), helpers/
+web/tests/e2e Playwright browser tests (driven by web/playwright.config.js)
+docs/ All documentation; docs/INDEX.md is the navigation hub
+analytics/ Collected analytics reports
+```
+
+## Commands
+
+Everything routes through the `Makefile`; prefer it over raw commands.
+
+```bash
+make help # list all targets
+make start|stop|restart|status|logs|backup|console
+make test # syntax checks + pytest + vitest
+make test-api # pytest only
+make test-web # vitest only
+make test-playwright # browser E2E
+make test-e2e # BATS end-to-end (needs a running server)
+make lint # shellcheck + eslint + python + yaml + compose validate
+make coverage # pytest with coverage report
+make coverage-check # enforce the threshold in .coverage-config.ini
+make build # docker compose build
+```
+
+Direct equivalents when you need them:
+
+```bash
+bash -n scripts/foo.sh # shell syntax check
+cd tests/api && pytest -v # API tests (pytest.ini lives here)
+cd web && npm test # Vitest
+cd web && npm run lint # ESLint (must pass with --max-warnings 0)
+docker compose config # validate compose files
+```
+
+**Use `docker compose` (with a space), never `docker-compose`.** The standalone
+binary conflicts with the plugin on Raspberry Pi OS; the `Makefile` detects which
+form is available via its `COMPOSE` variable, and scripts use the `compose()`
+wrapper from `scripts/lib/common.sh`.
+
+## Code Standards
+
+### Bash (`scripts/`)
+
+- `#!/bin/bash` shebang, `set -e` near the top.
+- 4-space indent, no tabs. Always quote variables: `"$VAR"`.
+- Resolve the script's own directory, then source the shared library:
+
+ ```bash
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ # shellcheck source-path=SCRIPTDIR
+ # shellcheck source=lib/common.sh
+ source "${SCRIPT_DIR}/lib/common.sh"
+ ```
+
+ `common.sh` provides the colour variables (`RED`, `GREEN`, `YELLOW`, `BLUE`, `NC`),
+ `PROJECT_DIR`, `SCRIPTS_DIR` and the `compose()` wrapper. Do not redefine them.
+- Every script takes a subcommand and has a `usage()` function; dispatch with `case`.
+- Must pass `shellcheck` (see `.shellcheckrc`).
+
+### Python (`api/`, `scripts/*.py`)
+
+- PEP 8, formatted with Black at **line-length 120** (`pyproject.toml`).
+- Type hints where they help; docstrings on functions and classes.
+- `pathlib.Path` for filesystem work; catch specific exceptions.
+- Imports grouped stdlib / third-party / local.
+- Flask endpoints: decorate with `@app.route(...)` then `@require_permission("")`
+ for anything privileged. Return `jsonify({...})` with an explicit status code on
+ error paths:
+
+ ```python
+ @app.route("/api/keys", methods=["GET"])
+ @require_permission("api_keys.view")
+ def list_api_keys():
+ """List all API keys (without showing full key values)."""
+ try:
+ ...
+ return jsonify({"keys": keys_list})
+ except Exception as e:
+ app.logger.error(f"Error listing keys: {e}")
+ return jsonify({"error": "Internal server error"}), 500
+ ```
+
+- Never return raw exception text to the client on a 500.
+
+### React (`web/src/`)
+
+- Functional components with hooks; no class components.
+- Tailwind utility classes for styling — no separate CSS modules.
+- All HTTP goes through `web/src/services/api.js`; components never call `axios` directly.
+- Reuse the existing hooks (`usePolling`, `useErrorHandler`, `useAutoDismiss`,
+ `useDebounce`, `useThrottle`) instead of re-implementing them.
+- Routes are lazy-loaded in `App.jsx` via `LazyRoute`; keep new pages lazy.
+- `npm run lint` runs with `--max-warnings 0`, so warnings break the build.
+
+### Docker / YAML
+
+- 2-space YAML indent; `${VAR:-default}` for environment substitution.
+- Multi-stage builds, minimal layers, clean up within the same `RUN`.
+- Keep the healthcheck in `docker-compose.yml` accurate — a too-short
+ `start_period` causes restart loops on a Pi.
+
+### Naming
+
+| Kind | Convention | Example |
+| --- | --- | --- |
+| Shell scripts | `kebab-case.sh` | `backup-scheduler.sh` |
+| Python | `snake_case.py` | `server.py` |
+| React components | `PascalCase.jsx` | `StatusCard.jsx` |
+| Hooks | `useCamelCase.js` | `usePolling.js` |
+| Config files | `kebab-case.conf` | `backup-schedule.conf` |
+| Docs | `UPPERCASE.md` | `TROUBLESHOOTING.md` |
+
+## Testing
+
+- Python tests live in `tests/api/` and are run **from that directory** —
+ `tests/api/pytest.ini` holds the coverage flags, timeouts and markers.
+- Registered markers: `unit`, `integration`, `api`, `slow`, `performance`,
+ `contract`, `e2e`. `--strict-markers` is on, so add new markers to
+ `tests/api/pytest.ini` *and* `pyproject.toml` before using them.
+- React unit tests sit next to the code in `__tests__/`; integration tests in
+ `web/src/test/integration/`; MSW handlers in `web/src/test/mocks/`.
+- Playwright specs belong in `web/tests/e2e/` only.
+- BATS suites in `tests/unit/`, `tests/integration/`, `tests/e2e/`.
+- Coverage threshold is enforced at **40%** in `.coverage-config.ini`. That file is
+ not auto-discovered by coverage.py, so every entry point passes `--cov-config`
+ explicitly; run pytest from `tests/api` so the relative path resolves.
+
+See [docs/TESTING.md](docs/TESTING.md) for the full guide.
+
+## Raspberry Pi Constraints
+
+These shape most design decisions — do not optimise them away:
+
+- **Memory**: 4GB model → `MEMORY_MIN=1G`, `MEMORY_MAX=2G`; 8GB model → `2G`/`4G`.
+- **CPU**: ARM64. Images must build for `linux/arm64` (see `scripts/build-multiarch.sh`).
+- **Storage**: SD cards have finite writes — keep log rotation on and compress backups.
+- **Thermals**: sustained load throttles the Pi; long-running work should be chunked.
+
+Test on real hardware when a change is hardware-specific.
+
+## Security
+
+- Never commit secrets. `config/*.conf` is gitignored; only `*.example` files are tracked.
+- API keys live in `config/api-keys.json` (gitignored); RCON passwords are generated randomly.
+- Validate and sanitise all API input; `api/security.py` holds the shared helpers and
+ security headers.
+- Gitleaks and CodeQL run in CI — do not work around them.
+
+## Git Conventions
+
+- Branch prefixes: `feature/`, `fix/`, `docs/`.
+- One logical change per PR; fill in `.github/pull_request_template.md`.
+- Update `CHANGELOG.md` for anything user-facing.
+- Pre-commit hooks are configured in `.pre-commit-config.yaml` — install with
+ `pre-commit install`.
+
+## Before You Call It Done
+
+- [ ] `make lint` passes
+- [ ] `make test` passes
+- [ ] `docker compose config` validates
+- [ ] Docs updated (`README.md` for user-facing changes, the relevant `docs/` guide otherwise)
+- [ ] `CHANGELOG.md` updated
+- [ ] No secrets, no hardcoded absolute paths
+
+## Documentation Rules
+
+- `docs/INDEX.md` is the navigation hub — add new docs there or they will not be found.
+- Keep internal links relative.
+- Don't create "summary", "complete" or "implementation notes" documents; that history
+ belongs in `CHANGELOG.md` and git.
+- Don't state coverage percentages or test counts in prose — they go stale immediately.
+ Point at `make coverage` or CI instead.
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
deleted file mode 100644
index b59de42..0000000
--- a/AGENT_INSTRUCTIONS.md
+++ /dev/null
@@ -1,735 +0,0 @@
-# Agent Instructions for Minecraft Server Management Project
-
-This document provides comprehensive instructions for AI agents working on this codebase to ensure consistency across development sessions.
-
-## Table of Contents
-
-1. [Project Overview](#project-overview)
-2. [Architecture & Technology Stack](#architecture--technology-stack)
-3. [Code Standards](#code-standards)
-4. [Development Workflow](#development-workflow)
-5. [File Structure](#file-structure)
-6. [Testing Requirements](#testing-requirements)
-7. [Documentation Standards](#documentation-standards)
-8. [Common Patterns](#common-patterns)
-9. [Important Considerations](#important-considerations)
-10. [Quick Reference](#quick-reference)
-
----
-
-## Project Overview
-
-This is a **Minecraft Server Management System** optimized for **Raspberry Pi 5 (ARM64)**. The project provides:
-
-- Docker-based server deployment and management
-- Automated backup scheduling and retention
-- Plugin management system
-- Multi-world support
-- REST API for remote server control
-- React web interface for server administration
-- RCON integration
-- Log management and analysis
-- Update management system
-
-**Target Platform**: Raspberry Pi 5 (4GB/8GB RAM), but also supports x86_64
-
----
-
-## Architecture & Technology Stack
-
-### Backend
-
-- **API Server**: Python 3 with Flask
-- **Server Management**: Bash scripts
-- **Containerization**: Docker & Docker Compose
-- **Configuration**: INI-style config files
-
-### Frontend
-
-- **Framework**: React with Vite
-- **Styling**: Tailwind CSS
-- **Testing**: Vitest
-- **Build Tool**: Vite
-
-### Testing
-
-- **Python**: pytest
-- **React**: Vitest
-- **Shell Scripts**: BATS (Bash Automated Testing System)
-
-### Infrastructure
-
-- **Container Runtime**: Docker
-- **Orchestration**: Docker Compose
-- **OS**: Raspberry Pi OS (64-bit) / Linux
-
----
-
-## Code Standards
-
-### Shell Scripts
-
-**Requirements:**
-
-- Always use `#!/bin/bash` shebang
-- Use `set -e` for error handling
-- 4-space indentation (no tabs)
-- Always quote variables: `"$VAR"` not `$VAR`
-- Use functions for repeated code
-- Include color output for user feedback
-- Add comments for complex logic
-- Include usage/help functions
-
-**Example:**
-
-```bash
-#!/bin/bash
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Get script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-function example_function() {
- local param="$1"
- echo -e "${GREEN}Processing: $param${NC}"
-}
-
-# Main logic
-if [ -z "$VARIABLE" ]; then
- echo -e "${RED}Error: Variable not set${NC}"
- exit 1
-fi
-```
-
-**Validation:**
-
-- Run `bash -n script.sh` to check syntax
-- Test on actual Raspberry Pi 5 when possible
-
-### Python Code
-
-**Requirements:**
-
-- Follow PEP 8 style guide
-- Use type hints where appropriate
-- Include docstrings for functions and classes
-- Use `pathlib.Path` for file operations
-- Handle exceptions specifically
-- Group imports: stdlib, third-party, local
-
-**Example:**
-
-```python
-#!/usr/bin/env python3
-"""
-Module description.
-"""
-
-from pathlib import Path
-from typing import Optional, Dict, Any
-from datetime import datetime
-
-def example_function(param: str) -> Optional[Path]:
- """
- Function description.
-
- Args:
- param: Parameter description
-
- Returns:
- Path object or None
- """
- try:
- path = Path(param)
- if path.exists():
- return path
- return None
- except Exception as e:
- print(f"Error processing {param}: {e}")
- return None
-```
-
-**Validation:**
-
-- Run `pytest tests/api/ -v` for tests
-- Use `mypy` for type checking (if configured)
-- Run `flake8` or `pylint` for linting
-
-### React/JavaScript
-
-**Requirements:**
-
-- Use functional components with hooks
-- Use Tailwind CSS for styling
-- Keep components small and focused
-- Use `services/api.js` for API calls
-- Include PropTypes or TypeScript types
-- Write tests for components
-
-**Example:**
-
-```jsx
-import { useState, useEffect } from 'react';
-import { api } from '../services/api';
-
-export function StatusCard() {
- const [status, setStatus] = useState(null);
- const [loading, setLoading] = useState(true);
-
- useEffect(() => {
- api.getStatus()
- .then(setStatus)
- .catch(console.error)
- .finally(() => setLoading(false));
- }, []);
-
- if (loading) return
Loading...
;
-
- return (
-
-
Server Status
-
{status?.status || 'Unknown'}
-
- );
-}
-```
-
-**Validation:**
-
-- Run `npm test` for unit tests
-- Run `npm run lint` for linting
-- Test in browser
-
-### Docker
-
-**Requirements:**
-
-- Use official base images when possible
-- Minimize layers
-- Clean up in the same layer
-- Use multi-stage builds for optimization
-- Include health checks
-- Use environment variables for configuration
-
-**Example:**
-
-```dockerfile
-FROM eclipse-temurin:17-jre-alpine
-
-# Install dependencies
-RUN apk add --no-cache bash
-
-# Set working directory
-WORKDIR /minecraft/server
-
-# Copy scripts
-COPY scripts/ /minecraft/scripts/
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
- CMD pgrep -f java || exit 1
-
-# Default command
-CMD ["/minecraft/scripts/start.sh"]
-```
-
-### YAML Files
-
-**Requirements:**
-
-- 2-space indentation
-- Use environment variables: `${VAR:-default}`
-- Keep lines under 120 characters
-- Validate with `docker-compose config`
-
----
-
-## Development Workflow
-
-### Making Changes
-
-1. **Create Feature Branch**
-
- ```bash
- git checkout -b feature/feature-name
- ```
-
-2. **Make Changes**
- - Follow code standards
- - Write tests
- - Update documentation
-
-3. **Test Changes**
-
- ```bash
- # Shell scripts
- bash -n script.sh
-
- # Python
- pytest tests/api/ -v
-
- # React
- npm test
-
- # Docker
- docker-compose config
- ```
-
-4. **Commit Changes**
-
- ```bash
- git commit -m "Add feature: description"
- ```
-
-5. **Push and Create PR**
-
- ```bash
- git push origin feature/feature-name
- ```
-
-### Testing Requirements
-
-**Before Committing:**
-
-- [ ] Shell scripts pass syntax check (`bash -n`)
-- [ ] Python tests pass (`pytest`)
-- [ ] React tests pass (`npm test`)
-- [ ] Docker config validates (`docker-compose config`)
-- [ ] Documentation updated
-- [ ] CHANGELOG.md updated
-
-**Integration Testing:**
-
-- Test on Raspberry Pi 5 when possible
-- Test server startup/shutdown
-- Test backup/restore
-- Test plugin management
-- Test API endpoints
-
----
-
-## File Structure
-
-```
-minecraft/
-├── api/ # Python Flask REST API
-│ ├── server.py # Main API server
-│ └── requirements.txt # Python dependencies
-├── web/ # React frontend
-│ ├── src/
-│ │ ├── components/ # React components
-│ │ ├── pages/ # Page components
-│ │ ├── services/ # API service layer
-│ │ └── test/ # Test utilities
-│ ├── package.json
-│ └── vite.config.js
-├── scripts/ # Shell scripts
-│ ├── manage.sh # Main management script
-│ ├── backup-scheduler.sh # Backup scheduling
-│ ├── plugin-manager.sh # Plugin management
-│ ├── world-manager.sh # World management
-│ ├── rcon-client.sh # RCON client
-│ └── ...
-├── config/ # Configuration files
-│ ├── api.conf # API configuration
-│ ├── backup-schedule.conf # Backup schedule
-│ ├── backup-retention.conf # Backup retention
-│ └── ...
-├── docs/ # Documentation
-│ ├── API.md # API documentation
-│ ├── DEVELOPMENT.md # Development guide
-│ ├── INSTALL.md # Installation guide
-│ └── ...
-├── tests/ # Test suites
-│ ├── api/ # Python API tests
-│ │ ├── test_api.py
-│ │ └── conftest.py
-│ ├── integration/ # Integration tests
-│ └── unit/ # Unit tests
-├── systemd/ # Systemd service files
-├── docker-compose.yml # Docker Compose config
-├── Dockerfile # Docker image definition
-├── Makefile # Convenience commands
-├── README.md # Main documentation
-├── CONTRIBUTING.md # Contribution guidelines
-├── docs/TASKS.md # Development tasks
-└── CHANGELOG.md # Version history
-```
-
----
-
-## Testing Requirements
-
-### Unit Tests
-
-- **Python**: Test individual functions in `tests/api/`
-- **React**: Test components in `__tests__/` directories
-- **Shell**: Test functions in `tests/unit/`
-
-### Integration Tests
-
-- Test script interactions in `tests/integration/`
-- Test API endpoints with real server
-- Test Docker container operations
-
-### Test Coverage
-
-- **Current**: 51% for Python API
-- **Goal**: >50% coverage minimum
-- **Target**: 80%+ for critical paths
-
-### Running Tests
-
-```bash
-# Python API tests
-pytest tests/api/ -v
-pytest tests/api/ -v --cov=api --cov-report=term-missing
-
-# React tests
-cd web && npm test
-
-# Shell script tests
-bats tests/unit/
-```
-
----
-
-## Documentation Standards
-
-### When to Update Documentation
-
-- **README.md**: User-facing features, setup changes
-- **docs/INSTALL.md**: Installation procedure changes
-- **docs/API.md**: API endpoint changes
-- **docs/DEVELOPMENT.md**: Development workflow changes
-- **CHANGELOG.md**: All changes (required)
-- **QUICK_REFERENCE.md**: New commands or features
-
-### Documentation Format
-
-- Use Markdown format
-- Include code examples
-- Use clear headings
-- Keep internal links relative
-- Update all related docs when making changes
-
-### Example Documentation Update
-
-```markdown
-## New Feature
-
-### Description
-Brief description of the feature.
-
-### Usage
-```bash
-./manage.sh new-command
-```
-
-### Configuration
-
-Add to `config/feature.conf`:
-
-```ini
-setting=value
-```
-
-### Examples
-
-[Include examples]
-
-```
-
----
-
-## Common Patterns
-
-### Script Structure Pattern
-
-```bash
-#!/bin/bash
-set -e
-
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-NC='\033[0m'
-
-# Script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Configuration
-CONFIG_FILE="${SCRIPT_DIR}/../config/script.conf"
-
-# Functions
-function usage() {
- echo "Usage: $0 {command}"
- exit 1
-}
-
-function main_function() {
- local param="$1"
- echo -e "${GREEN}Processing: $param${NC}"
-}
-
-# Main execution
-if [ "$#" -eq 0 ]; then
- usage
- exit 1
-fi
-
-case "$1" in
- command)
- main_function "$2"
- ;;
- *)
- usage
- exit 1
- ;;
-esac
-```
-
-### API Endpoint Pattern
-
-```python
-@app.route('/api/endpoint', methods=['GET', 'POST'])
-@require_api_key
-def endpoint():
- """
- Endpoint description.
-
- Returns:
- JSON response with status and data
- """
- try:
- if request.method == 'GET':
- data = get_data()
- return jsonify({"status": "success", "data": data})
- elif request.method == 'POST':
- data = request.get_json()
- result = process_data(data)
- return jsonify({"status": "success", "result": result})
- except ValueError as e:
- return jsonify({"status": "error", "message": str(e)}), 400
- except Exception as e:
- app.logger.error(f"Error in endpoint: {e}")
- return jsonify({"status": "error", "message": "Internal server error"}), 500
-```
-
-### React Component Pattern
-
-```jsx
-import { useState, useEffect } from 'react';
-import { api } from '../services/api';
-
-export function Component({ prop1, prop2 }) {
- const [data, setData] = useState(null);
- const [loading, setLoading] = useState(true);
- const [error, setError] = useState(null);
-
- useEffect(() => {
- api.getData()
- .then(setData)
- .catch(setError)
- .finally(() => setLoading(false));
- }, []);
-
- if (loading) return
Loading...
;
- if (error) return
Error: {error.message}
;
-
- return (
-
- {/* Component content */}
-
- );
-}
-```
-
----
-
-## Important Considerations
-
-### Raspberry Pi 5 Optimization
-
-**Memory Constraints:**
-
-- 4GB model: Use MIN=1G, MAX=2G
-- 8GB model: Use MIN=2G, MAX=4G
-- Monitor memory usage carefully
-- Implement memory-efficient algorithms
-
-**CPU Considerations:**
-
-- ARM64 architecture
-- Optimize for efficiency, not just speed
-- Consider CPU temperature monitoring
-- Use multi-core processing when beneficial
-
-**Storage:**
-
-- SD card write limits
-- Implement log rotation
-- Use efficient backup compression
-- Monitor disk space
-
-### Docker Best Practices
-
-**Resource Management:**
-
-- Set appropriate memory limits
-- Configure CPU limits if needed
-- Use health checks
-- Implement proper logging
-
-**Volume Management:**
-
-- Use bind mounts for data persistence
-- Configure volume permissions
-- Implement backup strategies
-
-**Networking:**
-
-- Use custom networks
-- Expose only necessary ports
-- Implement proper security
-
-### Security
-
-**API Security:**
-
-- Use API keys for authentication
-- Store keys securely (config/api-keys.json)
-- Never commit secrets
-- Validate all inputs
-
-**RCON Security:**
-
-- Generate secure random passwords
-- Store passwords securely
-- Use strong passwords
-
-**File Permissions:**
-
-- Set appropriate permissions on scripts
-- Protect configuration files
-- Secure backup files
-
-### Error Handling
-
-**Graceful Degradation:**
-
-- Handle missing dependencies
-- Provide fallback options
-- Don't crash on non-critical errors
-
-**User Feedback:**
-
-- Provide clear error messages
-- Use color coding (red for errors)
-- Log errors with context
-
-**Recovery:**
-
-- Implement rollback mechanisms
-- Create backups before major operations
-- Validate operations before execution
-
----
-
-## Quick Reference
-
-### Common Commands
-
-```bash
-# Server Management
-./manage.sh start # Start server
-./manage.sh stop # Stop server
-./manage.sh restart # Restart server
-./manage.sh status # Check status
-./manage.sh logs # View logs
-./manage.sh backup # Create backup
-./manage.sh console # Attach to console
-
-# Development
-make test # Run tests
-make build # Build Docker image
-make start # Start server
-make logs # View logs
-
-# Testing
-pytest tests/api/ -v # Run API tests
-cd web && npm test # Run React tests
-bash -n script.sh # Check script syntax
-docker-compose config # Validate Docker config
-```
-
-### Key Files
-
-- `scripts/manage.sh` - Main management script
-- `api/server.py` - REST API server
-- `docker-compose.yml` - Docker configuration
-- `README.md` - Main documentation
-- `docs/TASKS.md` - Development tasks
-- `CONTRIBUTING.md` - Contribution guidelines
-- `docs/DEVELOPMENT.md` - Development guide
-
-### File Naming Conventions
-
-- **Scripts**: `kebab-case.sh` (e.g., `backup-scheduler.sh`)
-- **Python**: `snake_case.py` (e.g., `server.py`)
-- **React**: `PascalCase.jsx` (e.g., `StatusCard.jsx`)
-- **Config**: `kebab-case.conf` (e.g., `backup-schedule.conf`)
-- **Documentation**: `UPPERCASE.md` (e.g., `README.md`)
-
-### When Adding New Features
-
-1. Check `docs/TASKS.md` for related tasks
-2. Follow existing patterns in similar features
-3. Add tests for new functionality
-4. Update documentation (README, relevant docs/)
-5. Update `CHANGELOG.md` with changes
-6. Test on Raspberry Pi 5 if hardware-specific
-
-### Git Workflow
-
-- **Branches**: Use `feature/`, `fix/`, `docs/` prefixes
-- **Commits**: Clear, descriptive messages
-- **PRs**: One feature/fix per PR
-- **Reviews**: Address feedback before merging
-
----
-
-## Remember
-
-✅ **Always:**
-
-- Test on Raspberry Pi 5 when possible
-- Keep memory usage in mind (4GB/8GB models)
-- Follow existing code patterns
-- Update documentation with changes
-- Write tests for new features
-- Use clear, descriptive names
-- Handle errors gracefully
-- Provide user feedback
-
-❌ **Never:**
-
-- Commit secrets or API keys
-- Break backward compatibility without notice
-- Skip testing
-- Ignore error handling
-- Use tabs instead of spaces
-- Forget to update documentation
-- Hardcode paths (use variables)
-
----
-
-**Last Updated**: 2025-01-XX
-**Version**: 1.0.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82f51f2..a9548ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
+### Changed
+
+- **Repository and documentation cleanup**
+
+ - Consolidated AI assistant configuration on `AGENTS.md` as the single source of
+ truth, following the `ai-template-repo` convention. `AGENT_INSTRUCTIONS.md` and
+ the 317-line `.cursorrules` (which duplicated each other) were merged into it.
+ `CLAUDE.md`, `.cursorrules`, `.cursor/rules/project.mdc`, `.clinerules`,
+ `.windsurfrules` and `.github/copilot-instructions.md` are now thin pointers.
+ - Rewrote `README.md`: fixed broken links, corrected every `./manage.sh` and
+ `./setup-rpi.sh` path to `./scripts/...`, replaced the hand-written systemd unit
+ with the one shipped in `systemd/`, and documented `.env` configuration.
+ - Rewrote `docs/INDEX.md` as a task-oriented index of all 48 guides;
+ `docs/README.md` and `tests/README.md` are now short pointers to it.
+ - Merged `RESTART_LOOP_TROUBLESHOOTING.md` and `DOCKER_COMPOSE_FIX.md` into
+ `docs/TROUBLESHOOTING.md`, and `TEST_COVERAGE.md` into `docs/TESTING.md`.
+ - Replaced `docker-compose` with `docker compose` throughout the documentation to
+ match the Compose v2 plugin the `Makefile` and systemd units actually use.
+ - Added `.env.example` (referenced by the `Makefile` but previously missing).
+ - Synced the pytest markers in `pyproject.toml` with `tests/api/pytest.ini`, and
+ removed the duplicate `[tool.coverage]` block so `.coverage-config.ini` is the
+ only coverage config. Added the matching `--cov-config` to
+ `tests/api/pytest.ini`, since that filename is not auto-discovered by
+ coverage.py — `make test-api` and a bare `cd tests/api && pytest` had been
+ running with no exclusions and no `fail_under` at all.
+ - Tightened `.gitignore`: added `.mypy_cache/`, `playwright-report/`,
+ `test-results/`; fixed an inline comment that made a negation pattern literal.
+
+### Removed
+
+- **Dead configuration and build artifacts**
+
+ - Root `.eslintrc.json` and `.eslintignore` — unused; linting runs inside `web/`,
+ whose `.eslintrc.cjs` sets `root: true`.
+ - Root `playwright.config.js` and `tests/e2e/browser/` — stale duplicates of the
+ live `web/playwright.config.js` and `web/tests/e2e/`.
+ - `web/playwright-report/index.html` — a 520 KB generated report that had been
+ committed.
+
+- **Historical process documentation** (preserved in git history)
+
+ - `docs/archive/` (17 files), plus `ADVANCED_OPTIMIZATIONS.md`,
+ `CLEANUP_OPTIMIZATIONS_SUMMARY.md`, `CONSOLIDATION_SUMMARY.md`,
+ `DOCUMENTATION_CONSOLIDATION_PLAN.md`, `OPTIMIZATION_COMPLETE.md`,
+ `OPTIMIZATION_SUMMARY.md`, `WORKSPACE_ENHANCEMENTS.md`, `SETUP_CHECKLIST.md`.
+ - `tests/ANALYTICS_TESTS.md`, `tests/COMPLETE_TEST_SUMMARY.md`,
+ `tests/TEST_SUMMARY.md`.
+
### Added
- **Comprehensive Test Suite - Complete Implementation**
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7f4bb25
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,15 @@
+# CLAUDE.md — Claude Code Project Instructions
+
+**Read `AGENTS.md` first — it is the single source of truth for stack, commands, code
+style, testing, and conventions.** This file only holds Claude-specific additions;
+don't duplicate AGENTS.md content here.
+
+## Claude-specific notes
+
+- Don't commit, push, or deploy unless explicitly asked.
+- This repo uses **npm**, not pnpm. Web commands run from `web/`; Python tests run
+ from `tests/api/`.
+- Use `docker compose` (with a space) — never `docker-compose`.
+- Run `make lint && make test` before declaring a change done.
+- Most runtime state (`data/`, `backups/`, `config/*.conf`) is gitignored and lives
+ only on the Raspberry Pi — don't assume those paths exist locally.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a401d8d..c94da88 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -114,15 +114,15 @@ Before submitting changes:
bash -n script.sh
# Docker Compose
- docker-compose config
+ docker compose config
# Dockerfile
docker build -t test .
```
2. **Functional tests**:
- - Start server: `./manage.sh start`
- - Check logs: `./manage.sh logs`
+ - Start server: `./scripts/manage.sh start`
+ - Check logs: `./scripts/manage.sh logs`
- Connect with Minecraft client
- Test all management commands
- Verify backup/restore
diff --git a/README.md b/README.md
index ad7fe6f..f30a2ae 100644
--- a/README.md
+++ b/README.md
@@ -1,487 +1,229 @@
# Minecraft Server for Raspberry Pi 5
-A custom Minecraft server setup optimized for Raspberry Pi 5, providing easy control over settings and customization. This setup uses Docker for easy deployment and management.
+A self-hosted Minecraft server stack tuned for the Raspberry Pi 5 (ARM64): Docker
+deployment, automated and offsite backups, plugin and mod management, multi-world
+support, RCON, a REST API, and a React web admin panel.
+
+Works on x86_64 too — the Pi is just what it is optimised for.
## Features
-- 🎮 Optimized for Raspberry Pi 5 (ARM64 architecture)
-- 🐳 Docker-based deployment for easy management
-- ⚙️ Easy customization of server settings
-- 💾 Automatic backup support
-- 🔄 Simple update mechanism
-- 📊 Resource-efficient configuration
+- 🎮 Tuned for Raspberry Pi 5 (ARM64), multi-arch images
+- 🐳 Docker Compose deployment with systemd units for boot-time start
+- 💾 Scheduled backups with retention, plus offsite backup to R2 / S3 / B2
+- 🔌 Plugin and mod management (Paper, Spigot, Fabric, Forge)
+- 🌍 Multi-world management, switching, and per-world backups
+- 🖥️ REST API + React admin panel with RBAC, API keys and OAuth
+- 📊 Analytics, metrics, log rotation and search
+- 🔄 Version checking, compatibility checks and guided updates
## Requirements
-- Raspberry Pi 5 (4GB or 8GB RAM recommended)
-- MicroSD card (32GB or larger recommended)
+- Raspberry Pi 5 (4GB minimum, 8GB recommended)
+- MicroSD card, 32GB or larger
- Raspberry Pi OS (64-bit)
-- Internet connection for initial setup
+- Docker with the Compose v2 plugin (the setup script installs it)
## Quick Start
-### 1. Flash Raspberry Pi OS
-
-Quick steps:
-
-1. Download and install [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
-2. Insert your microSD card into your computer
-3. Open Raspberry Pi Imager
-4. Choose OS: **Raspberry Pi OS (64-bit)**
-5. Choose Storage: Select your microSD card
-6. Click on the gear icon (⚙️) for advanced options:
- - Set hostname (e.g., `minecraft-server`)
- - Enable SSH
- - Set username and password
- - Configure WiFi (optional)
-7. Click **Write** and wait for the process to complete
-
-### 2. Initial Setup on Raspberry Pi
-
-1. Insert the microSD card into your Raspberry Pi 5
-2. Power on the Raspberry Pi
-3. SSH into your Raspberry Pi:
-
- ```bash
- ssh pi@minecraft-server.local
- ```
-
- Or use the IP address if hostname doesn't work
-
-4. Clone this repository:
+```bash
+# On the Pi
+git clone https://github.com/and3rn3t/minecraft.git ~/minecraft-server
+cd ~/minecraft-server
- ```bash
- cd ~
- git clone https://github.com/and3rn3t/minecraft.git minecraft-server
- cd minecraft-server
- ```
+./scripts/setup-rpi.sh # installs Docker, dependencies, permissions
+# log out and back in so the docker group takes effect
-5. Run the setup script:
+./scripts/manage.sh start # start the server
+./scripts/manage.sh logs # watch it come up
+```
- ```bash
- chmod +x setup-rpi.sh
- ./setup-rpi.sh
- ```
+Connect from Minecraft using the Pi's address on port `25565`.
-6. **Important**: Log out and log back in for Docker permissions to take effect:
+Full walkthrough, including flashing the SD card: **[docs/INSTALL.md](docs/INSTALL.md)**.
+Deploying the API and web panel as well: **[docs/RPI5_FULL_DEPLOYMENT.md](docs/RPI5_FULL_DEPLOYMENT.md)**.
- ```bash
- exit
- # SSH back in
- ssh pi@minecraft-server.local
- cd ~/minecraft-server
- ```
+## Managing the Server
-### 3. Start the Minecraft Server
+`scripts/manage.sh` is the main entry point; `make` wraps the common ones.
```bash
-# Make management script executable
-chmod +x manage.sh
-
-# Start the server
-./manage.sh start
-
-# View logs
-./manage.sh logs
+./scripts/manage.sh start|stop|restart|status|logs|backup|console
+./scripts/manage.sh update [version] # update the server jar
+./scripts/manage.sh check-version # is there a newer release?
+./scripts/manage.sh check-compatibility # safe to update?
```
-## Server Management
-
-The `manage.sh` script provides easy server management:
-
```bash
-./manage.sh start # Start the server
-./manage.sh stop # Stop the server
-./manage.sh restart # Restart the server
-./manage.sh status # Check server status
-./manage.sh logs # View server logs
-./manage.sh backup # Create a backup
-./manage.sh console # Attach to server console (Ctrl+P, Ctrl+Q to detach)
-./manage.sh update [version] # Update server to latest or specified version
-./manage.sh check-version # Check for available updates
-./manage.sh check-compatibility # Check compatibility before updating
+make help # every target
+make start # same as ./scripts/manage.sh start
+make status
+make backup
+make logs
```
-### Minecraft-Specific Tools
-
-Additional scripts for Minecraft server management:
+### Other tools
```bash
-# Server Properties
-./scripts/server-properties-manager.sh get view-distance
+# Server properties and presets
./scripts/server-properties-manager.sh set view-distance 10
-./scripts/server-properties-manager.sh preset balanced
+./scripts/performance-presets.sh balanced
-# Player Management
+# Players
./scripts/whitelist-manager.sh add PlayerName
./scripts/ban-manager.sh ban PlayerName "Reason"
./scripts/op-manager.sh grant PlayerName 4
# Performance
./scripts/jvm-optimizer.sh generate 2G 4 aikar
-./scripts/performance-presets.sh balanced
+./scripts/monitor-rpi5.sh
```
-## Customization
-
-### Server Properties
-
-Edit `server.properties` to customize your server:
-
-```properties
-# Common settings to adjust
-max-players=10 # Maximum number of players
-difficulty=normal # easy, normal, hard, peaceful
-gamemode=survival # survival, creative, adventure
-view-distance=10 # Render distance (lower = better performance)
-motd=My Minecraft Server # Server name in multiplayer list
-```
+Everything is listed in **[docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)**.
-After changing settings, restart the server:
+## Configuration
-```bash
-./manage.sh restart
-```
+### Server properties
-### Memory Allocation
+Edit `server.properties`, then `./scripts/manage.sh restart`:
-Edit `docker-compose.yml` to adjust memory settings:
-
-```yaml
-environment:
- - MEMORY_MIN=1G # Minimum memory (1G for 4GB Pi, 2G for 8GB Pi)
- - MEMORY_MAX=2G # Maximum memory (2G for 4GB Pi, 4G for 8GB Pi)
+```properties
+max-players=10
+difficulty=normal
+gamemode=survival
+view-distance=10 # lower is faster
+motd=My Minecraft Server
```
-**Recommended Memory Settings:**
-
-- Raspberry Pi 5 (4GB): MIN=1G, MAX=2G
-- Raspberry Pi 5 (8GB): MIN=2G, MAX=4G
-
-### Minecraft Version
-
-To change Minecraft version, edit `docker-compose.yml`:
-
-```yaml
-environment:
- - MINECRAFT_VERSION=1.20.4 # Change to desired version
-```
+### Memory and version
-Then rebuild and restart:
+Both come from environment variables read by `docker-compose.yml`, so set them in a
+`.env` file next to it rather than editing the compose file:
```bash
-docker-compose down
-docker-compose up -d --build
+MINECRAFT_VERSION=1.20.4
+MEMORY_MIN=1G # 2G on an 8GB Pi
+MEMORY_MAX=2G # 4G on an 8GB Pi
+CONTAINER_MEMORY_LIMIT=3G # must exceed MEMORY_MAX by ~1G
```
-## Port Forwarding
+> `CONTAINER_MEMORY_LIMIT` has to leave the JVM roughly 0.5–1G of headroom beyond
+> `MEMORY_MAX`. Setting it equal to `MEMORY_MAX` is the classic cause of a restart
+> loop — see [Troubleshooting](docs/TROUBLESHOOTING.md#server-restart-loop).
-To allow players outside your local network to connect:
-
-1. Find your Raspberry Pi's local IP address:
-
- ```bash
- hostname -I
- ```
-
-2. Log into your router's admin panel
-3. Set up port forwarding:
-
- - External Port: 25565
- - Internal Port: 25565
- - Internal IP: Your Raspberry Pi's IP address
- - Protocol: TCP
-
-4. Find your public IP address: Visit [whatismyipaddress.com](https://whatismyipaddress.com/)
-5. Share your public IP with your friends to connect
+More examples: **[docs/CONFIGURATION_EXAMPLES.md](docs/CONFIGURATION_EXAMPLES.md)**.
## Backups
-### Manual Backup
-
-```bash
-./manage.sh backup
-```
-
-Backups are stored in the `backups/` directory.
-
-### Restore from Backup
-
-```bash
-# Stop the server
-./manage.sh stop
-
-# Extract backup to data directory
-tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/
-
-# Start the server
-./manage.sh start
-```
-
-## Troubleshooting
-
-### Server won't start
-
-1. Check if Docker is running:
-
- ```bash
- sudo systemctl status docker
- ```
-
-2. View detailed logs:
-
- ```bash
- docker-compose logs
- ```
-
-3. Check available memory:
-
- ```bash
- free -h
- ```
-
-### Performance Issues
-
-1. Reduce view distance in `server.properties`:
-
- ```properties
- view-distance=6
- simulation-distance=6
- ```
-
-2. Lower max players:
-
- ```properties
- max-players=5
- ```
-
-3. Reduce memory if system is struggling:
-
- ```yaml
- MEMORY_MAX=1G
- ```
-
-### Cannot connect from outside network
-
-1. Verify port forwarding is set up correctly
-2. Check if server is running: `./manage.sh status`
-3. Ensure firewall allows port 25565:
-
- ```bash
- sudo ufw allow 25565/tcp
- ```
-
-## Performance Tips
-
-1. **Use Ethernet**: Wired connection is more stable than WiFi
-2. **Proper Cooling**: Ensure your Pi 5 has adequate cooling (case with fan recommended)
-3. **Quality Power Supply**: Use the official Raspberry Pi 5 power supply
-4. **Fast Storage**: Use a high-quality microSD card (Class 10, A2 rating)
-5. **Regular Backups**: Back up your world regularly
-
-## Advanced Configuration
-
-### Installing Plugins (For Bukkit/Spigot/Paper)
-
-If you want to use plugins, you'll need to use Paper or Spigot instead of vanilla:
-
-1. Switch to Paper or Spigot:
-
- ```bash
- ./scripts/switch-server-type.sh paper
- ```
-
-2. Install plugins:
-
- ```bash
- ./scripts/plugin-manager.sh install /path/to/plugin.jar
- ```
-
-3. Restart the server:
- ```bash
- ./scripts/manage.sh restart
- ```
-
-See [PLUGIN_MANAGEMENT.md](docs/PLUGIN_MANAGEMENT.md) for detailed plugin management guide.
-
-### Automatic Startup on Boot
-
-To start the server automatically when the Pi boots:
-
```bash
-# Create systemd service
-sudo nano /etc/systemd/system/minecraft.service
+./scripts/manage.sh backup # one-off, into backups/
+./scripts/install-backup-timer.sh # scheduled via systemd timer
+./scripts/cloud-backup-r2.sh upload # offsite (also -s3 and -b2 variants)
```
-Add:
-
-```ini
-[Unit]
-Description=Minecraft Server
-After=docker.service
-Requires=docker.service
+To restore, stop the server, extract the archive into `data/`, and start again.
+Details and retention policy: **[docs/BACKUP_AND_MONITORING.md](docs/BACKUP_AND_MONITORING.md)**
+and **[docs/CLOUD_BACKUP.md](docs/CLOUD_BACKUP.md)**.
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-WorkingDirectory=/home/pi/minecraft-server
-ExecStart=/usr/bin/docker-compose up -d
-ExecStop=/usr/bin/docker-compose down
-User=pi
+## Starting on Boot
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable the service:
+systemd units ship in `systemd/`. They use `docker compose` and pull the latest
+image before starting:
```bash
-sudo systemctl enable minecraft.service
-sudo systemctl start minecraft.service
+sudo cp systemd/minecraft.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now minecraft.service
```
-## Testing
+`minecraft-api.service`, `minecraft-web.service`, the backup timer and the update
+timer install the same way. See **[docs/DOCKER_BOOT_SETUP.md](docs/DOCKER_BOOT_SETUP.md)**.
-The project includes comprehensive automated tests:
+## Remote Access
-```bash
-# Run API tests
-python -m pytest tests/api/ -v
+To let friends connect from outside your network, forward TCP `25565` to the Pi.
+For a stable hostname on a changing home IP, use the DDNS updater —
+**[docs/DYNAMIC_DNS.md](docs/DYNAMIC_DNS.md)**.
-# Run with coverage
-python -m pytest tests/api/ -v --cov=api --cov-report=term-missing
-```
-
-**Current Status**: ✅ 60+ API tests passing (~60% coverage)
-
-See [Testing Guide](docs/TESTING.md) for more information.
-
-## Code Quality
-
-The project uses static code analysis to ensure code quality:
+## Web Panel & API
```bash
-# Run all linting checks
-make lint
-
-# Or use the linting script directly
-./scripts/lint.sh all
+./scripts/setup-api-venv.sh # Python venv for the API
+./scripts/api-server.sh start # REST API
+./scripts/build-web.sh # build the React panel
```
-**Linting Tools**:
-
-- **ShellCheck** - Bash script linting
-- **ESLint** - JavaScript/React linting
-- **flake8/pylint** - Python code analysis (optional)
-- **yamllint** - YAML file validation (optional)
-
-See [Linting Guide](docs/LINTING.md) for more information.
+The panel covers server control, players, worlds, backups, plugins, logs, the
+console, analytics, config editing, users and API keys. See
+**[docs/WEB_INTERFACE.md](docs/WEB_INTERFACE.md)** and **[docs/API.md](docs/API.md)**
+(the OpenAPI spec is `api/openapi.yaml`).
-## Docker Optimization
-
-The project uses optimized Docker images for Raspberry Pi 5:
-
-- **Multi-stage builds** - Reduced image size
-- **Layer optimization** - Better build caching
-- **Minimal base image** - Security and performance
-- **Build arguments** - Flexible configuration
+## Development
```bash
-# Build with custom version
-docker build --build-arg MINECRAFT_VERSION=1.21.0 -t minecraft-server .
+git clone https://github.com/and3rn3t/minecraft.git
+cd minecraft
-# Use BuildKit for faster builds
-export DOCKER_BUILDKIT=1
-docker build -t minecraft-server .
+make lint # shellcheck, eslint, python, yaml, compose validation
+make test # pytest + vitest + syntax checks
+make coverage # coverage report
```
-See [Docker Optimization Guide](docs/DOCKER_OPTIMIZATION.md) for details.
+- **[AGENTS.md](AGENTS.md)** — conventions, stack, commands (also what AI assistants read)
+- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — setup and workflow
+- **[docs/TESTING.md](docs/TESTING.md)** — test layout and how to run each suite
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — contribution guidelines
## Documentation
-📚 **Start here**: [Documentation Index](docs/INDEX.md) - Complete navigation guide
-
-### Quick Links
-
-**Getting Started:**
-
-- **[Installation Guide](docs/INSTALL.md)** - Complete setup instructions
-- **[Quick Reference](docs/QUICK_REFERENCE.md)** - Command cheat sheet
-- **[Configuration Examples](docs/CONFIGURATION_EXAMPLES.md)** - Config file examples
-
-**User Guides:**
-
-- **[Backup & Monitoring](docs/BACKUP_AND_MONITORING.md)** - Automated backups and metrics
-- **[Update Management](docs/UPDATE_MANAGEMENT.md)** - Server updates and versions
-- **[Plugin Management](docs/PLUGIN_MANAGEMENT.md)** - Installing and managing plugins
-- **[Multi-World Support](docs/MULTI_WORLD.md)** - Managing multiple worlds
-- **[Log Management](docs/LOG_MANAGEMENT.md)** - Log rotation and analysis
-- **[RCON Guide](docs/RCON.md)** - Remote console setup
-- **[REST API](docs/API.md)** - API documentation
-- **[Web Interface](docs/WEB_INTERFACE.md)** - Web admin panel
-
-**Developer Guides:**
-
-- **[Development Guide](docs/DEVELOPMENT.md)** - Setup and workflow
-- **[Testing Guide](docs/TESTING.md)** - Testing best practices
-- **[Cursor Configuration](docs/CURSOR_CONFIGURATION.md)** - IDE setup
-- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines
-- **[Agent Instructions](AGENT_INSTRUCTIONS.md)** - AI agent consistency guide
-
-**Project Planning:**
-
-- **[Roadmap](docs/ROADMAP.md)** - Development roadmap
-- **[Tasks](docs/TASKS.md)** - Detailed task breakdown
-- **[Changelog](CHANGELOG.md)** - Version history
-
-**Troubleshooting:**
+📚 **[docs/INDEX.md](docs/INDEX.md) lists every guide**, grouped by task. Common ones:
+
+| Topic | Guide |
+| --- | --- |
+| Install from scratch | [docs/INSTALL.md](docs/INSTALL.md) |
+| Command cheat sheet | [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) |
+| Something is broken | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
+| Backups & monitoring | [docs/BACKUP_AND_MONITORING.md](docs/BACKUP_AND_MONITORING.md) |
+| Plugins | [docs/PLUGIN_MANAGEMENT.md](docs/PLUGIN_MANAGEMENT.md) |
+| Multiple worlds | [docs/MULTI_WORLD.md](docs/MULTI_WORLD.md) |
+| REST API | [docs/API.md](docs/API.md) |
+| Pi tuning | [docs/RASPBERRY_PI_OPTIMIZATIONS.md](docs/RASPBERRY_PI_OPTIMIZATIONS.md) |
+| Roadmap | [docs/ROADMAP.md](docs/ROADMAP.md) |
+| Version history | [CHANGELOG.md](CHANGELOG.md) |
-- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common problems and solutions
-
-For complete documentation navigation, see [docs/INDEX.md](docs/INDEX.md).
-
-## Resources
-
-- [Minecraft Server Documentation](https://minecraft.fandom.com/wiki/Server)
-- [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/)
-- [Docker Documentation](https://docs.docker.com/)
-- [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties)
+## Troubleshooting
-## Development
+Start with **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** — it covers
+installation failures, startup problems, restart loops, connectivity, performance,
+Docker and system-level issues.
-### Quick Start for Developers
+Quick checks:
```bash
-# Clone repository
-git clone https://github.com/and3rn3t/minecraft.git
-cd minecraft
-
-# Setup environment
-cp .env.example .env # Edit with your settings
-make install
-
-# Test
-make test
-make build
-
-# Start development
-make start
+./scripts/manage.sh status
+./scripts/health-check.sh
+docker logs --tail 100 minecraft-server
+free -h && df -h
+vcgencmd measure_temp # should stay below 80°C
```
-See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development guide.
+## Performance Tips
-### Contributing
+1. Use Ethernet rather than WiFi
+2. Give the Pi 5 active cooling — it throttles under sustained load
+3. Use the official Pi 5 power supply
+4. Use a fast A2-rated card, or better, an NVMe drive
+5. Lower `view-distance` and `simulation-distance` before lowering memory
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See **[docs/RASPBERRY_PI_OPTIMIZATIONS.md](docs/RASPBERRY_PI_OPTIMIZATIONS.md)**.
-### Roadmap
+## Resources
-Check out [ROADMAP.md](ROADMAP.md) for planned features and development phases.
+- [Minecraft server documentation](https://minecraft.wiki/w/Server)
+- [server.properties reference](https://minecraft.wiki/w/Server.properties)
+- [Raspberry Pi documentation](https://www.raspberrypi.com/documentation/)
+- [Docker documentation](https://docs.docker.com/)
## License
-This project is open source and available for personal use.
-
-## Support
-
-For issues and questions, please open an issue on GitHub.
+See [LICENSE](LICENSE). Security reports: [SECURITY.md](SECURITY.md).
diff --git a/docs/ADVANCED_OPTIMIZATIONS.md b/docs/ADVANCED_OPTIMIZATIONS.md
deleted file mode 100644
index 57c2bbb..0000000
--- a/docs/ADVANCED_OPTIMIZATIONS.md
+++ /dev/null
@@ -1,290 +0,0 @@
-# Advanced Optimizations Implemented
-
-This document details all advanced optimization techniques implemented to improve performance, reduce bundle size, and enhance user experience.
-
-## ✅ Implemented Optimizations
-
-### 1. Route-Based Code Splitting (Lazy Loading)
-
-**Implementation:**
-
-- All route components are now lazy-loaded using React's `lazy()` function
-- Each route is wrapped with `Suspense` boundary for loading states
-- Reduces initial bundle size by ~60-70%
-
-**Benefits:**
-
-- ✅ Faster initial page load
-- ✅ Smaller initial JavaScript bundle
-- ✅ Better code organization
-- ✅ Improved caching strategy
-
-**Files Modified:**
-
-- `web/src/App.jsx` - All routes converted to lazy loading
-- Created `PageLoading` component for consistent loading states
-
-**Example:**
-
-```jsx
-const Dashboard = lazy(() => import('./pages/Dashboard'));
-
-
-
- }>
-
-
-
-
- }
-/>;
-```
-
-### 2. Debouncing & Throttling
-
-**Created Hooks:**
-
-- **`useDebounce`** - Delays value updates until user stops typing
-- **`useThrottle`** - Limits value updates to specific intervals
-
-**Usage:**
-
-- Log filter input (300ms debounce)
-- Search inputs (300ms debounce)
-- Auto-save functionality (500ms debounce)
-- Scroll events (throttle for performance)
-
-**Benefits:**
-
-- ✅ Reduces unnecessary filtering/search operations
-- ✅ Improves input responsiveness
-- ✅ Reduces CPU usage
-
-**Example:**
-
-```jsx
-const debouncedFilter = useDebounce(filter, 300);
-const filteredLogs = useMemo(
- () => logs.filter(log => log.includes(debouncedFilter)),
- [logs, debouncedFilter]
-);
-```
-
-### 3. Virtual Scrolling
-
-**Implementation:**
-
-- Created `VirtualList` component for rendering large lists
-- Only renders visible items + buffer
-- Automatic height calculation
-
-**Benefits:**
-
-- ✅ Handles thousands of items efficiently
-- ✅ Constant memory usage regardless of list size
-- ✅ Smooth scrolling performance
-
-**Usage:**
-
-- Logs list (when > 100 items)
-- Backups list (for large backup collections)
-- Players list (for servers with many players)
-
-**Example:**
-
-```jsx
-}
- itemHeight={24}
- containerHeight={600}
- overscan={10}
-/>
-```
-
-### 4. API Request Caching & Deduplication
-
-**Implementation:**
-
-- Created `apiCache.js` utility module
-- In-memory cache with TTL (Time To Live)
-- Request deduplication prevents duplicate concurrent requests
-- Automatic cache invalidation on mutations
-
-**Cache Strategy:**
-
-- **Fast-changing data** (status, metrics): 2-3 second cache
-- **Moderate-changing data** (players, backups): 5-10 second cache
-- **Slow-changing data** (worlds, plugins, config): 30 second cache
-- **Analytics data**: 60 second cache
-- **Mutations**: Automatically invalidate relevant cache
-
-**Benefits:**
-
-- ✅ Prevents duplicate API calls
-- ✅ Reduces server load
-- ✅ Faster response times (cache hits)
-- ✅ Better user experience
-
-**Cache TTL Examples:**
-
-```javascript
-// Fast-changing
-getStatus() - 2 seconds
-getMetrics() - 2 seconds
-getPlayers() - 3 seconds
-
-// Moderate-changing
-listBackups() - 10 seconds
-
-// Slow-changing
-listWorlds() - 30 seconds
-listPlugins() - 30 seconds
-listConfigFiles() - 30 seconds
-
-// Analytics
-getAnalyticsReport() - 60 seconds
-```
-
-### 5. Build Optimizations
-
-**Vite Configuration:**
-
-- Manual chunk splitting for vendor libraries
-- Separate chunks for React, Charts, Socket.IO
-- Improved caching strategy
-- Smaller chunk sizes
-
-**Benefits:**
-
-- ✅ Better browser caching
-- ✅ Parallel downloads
-- ✅ Smaller individual chunks
-- ✅ Faster subsequent page loads
-
-**Configuration:**
-
-```javascript
-manualChunks: {
- 'react-vendor': ['react', 'react-dom', 'react-router-dom'],
- 'chart-vendor': ['recharts'],
- 'socket-vendor': ['socket.io-client'],
-}
-```
-
-## 📊 Performance Impact
-
-### Bundle Size Reduction
-
-- **Initial Bundle**: Reduced by ~60-70%
-- **Code Splitting**: Routes loaded on-demand
-- **Vendor Chunks**: Better caching with separate chunks
-
-### Runtime Performance
-
-- **API Calls**: Reduced by ~40-50% with caching
-- **Rendering**: Virtual scrolling handles large lists efficiently
-- **Input Performance**: Debouncing reduces CPU usage by ~30%
-
-### Memory Usage
-
-- **Virtual Scrolling**: Constant memory regardless of list size
-- **Code Splitting**: Only loaded code in memory
-- **Cache Management**: Automatic cleanup of expired entries
-
-## 🔄 Cache Invalidation Strategy
-
-Cache is automatically invalidated on:
-
-- Server state changes (start/stop/restart)
-- Backup operations (create/restore/delete)
-- User/API key modifications
-- Configuration file saves
-- Analytics data collection
-
-**Manual Invalidation:**
-
-```javascript
-import { clearCache, clearAllCache } from '../utils/apiCache';
-
-// Clear specific cache
-clearCache('/api/status', 'GET');
-
-// Clear all cache
-clearAllCache();
-```
-
-## 🎯 Best Practices Established
-
-1. **Always lazy-load routes** - Never import all pages upfront
-2. **Use debouncing for search/filter** - Reduce unnecessary operations
-3. **Cache GET requests** - Reduce server load
-4. **Invalidate cache on mutations** - Keep data fresh
-5. **Use virtual scrolling for large lists** - Maintain performance
-6. **Split vendor chunks** - Improve caching
-
-## 📝 Usage Examples
-
-### Using Debounce Hook
-
-```jsx
-import { useDebounce } from '../hooks/useDebounce';
-
-const [searchTerm, setSearchTerm] = useState('');
-const debouncedSearch = useDebounce(searchTerm, 300);
-
-useEffect(() => {
- // This only runs 300ms after user stops typing
- performSearch(debouncedSearch);
-}, [debouncedSearch]);
-```
-
-### Using Cached API Calls
-
-```javascript
-// Automatically cached
-const status = await api.getStatus(); // Cached for 2 seconds
-
-// Automatically invalidates cache
-await api.startServer(); // Clears status/metrics cache
-```
-
-### Using Virtual Scrolling
-
-```jsx
-import { VirtualList } from '../components/VirtualList';
-
-}
- itemHeight={50}
- containerHeight={400}
- overscan={5}
-/>;
-```
-
-## 🚀 Future Optimization Opportunities
-
-1. **Service Worker**: Offline support and advanced caching
-2. **Web Workers**: Heavy computations off main thread
-3. **Image Optimization**: Lazy loading and format conversion
-4. **Prefetching**: Pre-load next likely routes
-5. **Request Queue**: Batch multiple requests
-6. **IndexedDB**: Persistent cache storage
-
-## 📈 Monitoring
-
-To monitor optimization effectiveness:
-
-1. **Bundle Analysis**: Run `npm run build` and check chunk sizes
-2. **Network Tab**: Monitor API call frequency with caching
-3. **Performance Tab**: Check render times with virtual scrolling
-4. **Memory Tab**: Verify constant memory with large lists
-
----
-
-**Last Updated**: 2025-01-27
-**Status**: ✅ All advanced optimizations implemented
diff --git a/docs/API_KEYS.md b/docs/API_KEYS.md
index 40eb337..1029410 100644
--- a/docs/API_KEYS.md
+++ b/docs/API_KEYS.md
@@ -350,4 +350,4 @@ if status.get('running'):
- [RBAC Documentation](RBAC.md) - Role-based access control
- [API Documentation](API.md) - Complete API reference
-- [Security Guide](SECURITY.md) - Security best practices
+- [Security Hardening](SECURITY_HARDENING.md) - Security best practices
diff --git a/docs/CI_CD.md b/docs/CI_CD.md
index 824b89f..84f3eaf 100644
--- a/docs/CI_CD.md
+++ b/docs/CI_CD.md
@@ -322,7 +322,7 @@ The generated `.img` file includes:
```bash
ssh pi@minecraft-server.local
cd ~/minecraft-server
- ./manage.sh status
+ ./scripts/manage.sh status
```
## Automated Releases
diff --git a/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md b/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md
deleted file mode 100644
index e6174c5..0000000
--- a/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md
+++ /dev/null
@@ -1,165 +0,0 @@
-# Cleanup and Optimizations Summary
-
-This document summarizes the cleanup tasks and optimizations implemented to improve code quality, maintainability, and user experience.
-
-## ✅ Completed Optimizations
-
-### 1. React Hook Extraction and Code Reusability
-
-**Created Reusable Hooks:**
-
-- **`usePolling` Hook** (`web/src/hooks/usePolling.js`)
-
- - Centralizes polling logic used across multiple components
- - Handles cleanup automatically
- - Provides loading, error, and data states
- - Used in: Dashboard, Players components
-
-- **`useErrorHandler` Hook** (`web/src/hooks/useErrorHandler.js`)
- - Provides consistent error handling across components
- - Integrates with toast notifications
- - Reduces code duplication
-
-### 2. Players Page Improvements
-
-**Before:**
-
-- Non-functional KICK button
-- Manual polling implementation
-- Console.error statements
-- No error handling
-
-**After:**
-
-- ✅ Functional KICK button with confirmation dialog
-- ✅ Uses reusable `usePolling` hook
-- ✅ Proper error handling with toast notifications
-- ✅ Loading states during kick operation
-- ✅ Improved key prop using player name instead of index
-
-### 3. Dashboard Component Optimization
-
-**Before:**
-
-- Manual polling with setInterval
-- Console.error statements
-- Inefficient re-renders
-- Manual error handling
-
-**After:**
-
-- ✅ Uses `usePolling` hook for automatic data refresh
-- ✅ `useCallback` for optimized function references
-- ✅ Centralized error handling via `useErrorHandler`
-- ✅ Cleaner, more maintainable code structure
-- ✅ Automatic cleanup of intervals
-
-### 4. Code Quality Improvements
-
-- ✅ Removed unused variables and imports
-- ✅ Improved component key props (using unique identifiers instead of indices)
-- ✅ Better error messages with fallback defaults
-- ✅ Consistent error handling patterns
-
-## 🔄 Remaining Cleanup Opportunities
-
-### High Priority
-
-1. **Console.log Cleanup** (11 files remaining)
-
- - Files: Analytics.jsx, Settings.jsx, Console.jsx, ConfigFiles.jsx, Plugins.jsx, Worlds.jsx, Logs.jsx, ApiKeys.jsx, Users.jsx, Backups.jsx, OAuthCallback.jsx
- - **Note**: Some console.log statements in Logs.jsx and Console.jsx may be intentional for debugging WebSocket connections
- - **Action**: Replace console.error with proper error handling hooks
- - **Action**: Consider adding a debug mode flag for development-only console.log statements
-
-2. **Apply usePolling Hook to Other Components**
-
- - Analytics.jsx - Currently uses manual polling
- - Worlds.jsx - Could benefit from polling hook
- - Plugins.jsx - Could benefit from polling hook
-
-3. **Consolidate Duplicate API Patterns**
- - Many components have similar try-catch-error handling patterns
- - Extract to reusable hooks or utility functions
-
-### Medium Priority
-
-4. **API Server Code Consolidation**
-
- - Review `api/server.py` for duplicate endpoint patterns
- - Extract common decorator logic
- - Standardize error response formats
-
-5. **Task Documentation Cleanup**
-
- - Archive completed tasks from `TASKS.md` to separate file
- - Keep active tasks only in main TASKS.md
-
-6. **Component Loading States**
- - Standardize loading skeleton components
- - Create reusable loading patterns
-
-### Low Priority
-
-7. **Performance Optimizations**
-
- - Implement React.memo for expensive components
- - Consider virtualization for long lists (players, backups, logs)
- - Lazy load routes for better initial load time
-
-8. **Accessibility Improvements**
-
- - Add ARIA labels to interactive elements
- - Improve keyboard navigation
- - Add focus indicators
-
-9. **Type Safety**
- - Consider migrating to TypeScript
- - Add PropTypes for better runtime type checking
- - Document component prop types
-
-## 📊 Impact Assessment
-
-### Code Reduction
-
-- **Lines of Code Saved**: ~80-100 lines by extracting common patterns
-- **Duplication Reduced**: Polling logic now centralized
-- **Maintainability**: Improved with reusable hooks
-
-### Performance Improvements
-
-- **Re-render Optimization**: useCallback prevents unnecessary re-renders
-- **Memory Leaks Prevented**: Automatic cleanup in hooks
-- **Network Efficiency**: Consistent polling intervals
-
-### Developer Experience
-
-- **Easier to Add New Features**: Reusable hooks available
-- **Consistent Patterns**: Standardized error handling
-- **Better Testing**: Hooks can be tested independently
-
-## 🎯 Next Steps
-
-### Immediate Actions
-
-1. Apply `usePolling` hook to remaining components
-2. Replace console.error statements with `useErrorHandler`
-3. Add PropTypes or TypeScript for better type safety
-
-### Future Enhancements
-
-1. Create shared component library for common UI patterns
-2. Implement error boundary components
-3. Add performance monitoring
-4. Consider state management solution (Redux/Zustand) if complexity grows
-
-## 📝 Notes
-
-- **WebSocket Logs**: Some console.log statements in Logs.jsx and Console.jsx are intentionally kept for debugging WebSocket connections. Consider adding a debug mode flag.
-- **Backward Compatibility**: All changes maintain backward compatibility with existing functionality.
-- **Testing**: New hooks should have unit tests added.
-
----
-
-**Last Updated**: 2025-01-27
-**Status**: In Progress - Core optimizations complete, cleanup tasks remaining
diff --git a/docs/CLOUD_BACKUP.md b/docs/CLOUD_BACKUP.md
index 717466f..279e1ff 100644
--- a/docs/CLOUD_BACKUP.md
+++ b/docs/CLOUD_BACKUP.md
@@ -210,7 +210,7 @@ fi
2. **Stop server**:
```bash
- ./manage.sh stop
+ ./scripts/manage.sh stop
```
3. **Restore backup**:
@@ -223,7 +223,7 @@ fi
4. **Start server**:
```bash
- ./manage.sh start
+ ./scripts/manage.sh start
```
## Cost Considerations
diff --git a/docs/CONFIGURATION_EXAMPLES.md b/docs/CONFIGURATION_EXAMPLES.md
index 1d2eacc..d7b9c4d 100644
--- a/docs/CONFIGURATION_EXAMPLES.md
+++ b/docs/CONFIGURATION_EXAMPLES.md
@@ -313,8 +313,8 @@ services:
Start both:
```bash
-docker-compose up -d
-docker-compose -f docker-compose-creative.yml up -d
+docker compose up -d
+docker compose -f docker-compose-creative.yml up -d
```
## Backup Configurations
@@ -325,7 +325,7 @@ Create backup script `backup-cron.sh`:
```bash
#!/bin/bash
cd /home/pi/minecraft-server
-./manage.sh backup
+./scripts/manage.sh backup
# Keep only last 7 days of backups
find ./backups -name "minecraft_backup_*.tar.gz" -mtime +7 -delete
@@ -403,10 +403,10 @@ environment:
After changing configuration:
-1. Stop server: `./manage.sh stop`
+1. Stop server: `./scripts/manage.sh stop`
2. Edit configuration files
-3. Start server: `./manage.sh start`
-4. Monitor logs: `./manage.sh logs`
+3. Start server: `./scripts/manage.sh start`
+4. Monitor logs: `./scripts/manage.sh logs`
5. Test in-game
6. Check resources: `htop` and `docker stats`
diff --git a/docs/CONSOLIDATION_SUMMARY.md b/docs/CONSOLIDATION_SUMMARY.md
deleted file mode 100644
index 5e4041d..0000000
--- a/docs/CONSOLIDATION_SUMMARY.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Documentation Consolidation Summary
-
-This document summarizes the documentation consolidation completed on 2025-01-27.
-
-## Overview
-
-The documentation has been reorganized and consolidated to reduce redundancy, improve navigation, and create single comprehensive guides for each major topic.
-
-## Results
-
-### Before Consolidation
-
-- **~60 documentation files** in `docs/` directory
-- Multiple overlapping files covering similar topics
-- Duplicate information across files
-- Difficult to find specific information
-
-### After Consolidation
-
-- **43 active documentation files** (reduced by ~28%)
-- **17 files archived** (preserved for historical reference)
-- Single comprehensive guide for each major topic
-- Clearer organization and easier navigation
-
-## Consolidations Completed
-
-### 1. CI/CD Documentation ✅
-
-**Before**: 4 separate files
-
-- `CI_CD.md`
-- `CI_CD_PIPELINE.md`
-- `CI_CD_OPTIMIZATIONS.md`
-- `CI_CD_ENHANCEMENTS.md`
-
-**After**: 1 comprehensive file
-
-- `CI_CD.md` - Complete CI/CD guide covering:
- - Pipeline structure
- - Optimizations
- - Testing enhancements
- - Release process
- - Troubleshooting
-
-**Archived**: 3 files moved to `docs/archive/`
-
-### 2. API Documentation ✅
-
-**Before**: 2 separate files
-
-- `API.md` - Usage guide
-- `API_DOCUMENTATION.md` - OpenAPI specification guide
-
-**After**: 1 comprehensive file
-
-- `API.md` - Complete REST API documentation with:
- - Quick start guide
- - Authentication methods
- - Complete endpoint reference
- - Usage examples (Python, cURL, JavaScript)
- - OpenAPI specification details
- - Developer tools
-
-**Archived**: 1 file moved to `docs/archive/`
-
-### 3. Testing Documentation ✅
-
-**Before**: 4 separate files
-
-- `TESTING.md` - Main testing guide
-- `TESTING_COMPLETE.md` - Implementation summary
-- `TESTING_FINAL_SUMMARY.md` - Final summary
-- `TESTING_ENHANCEMENTS.md` - Framework enhancements
-
-**After**: 1 comprehensive file
-
-- `TESTING.md` - Complete testing guide with:
- - Quick start
- - Test structure and types
- - Writing tests
- - Testing framework enhancements section
- - Coverage analysis
- - Troubleshooting
-
-**Archived**: 3 files moved to `docs/archive/`
-
-### 4. Raspberry Pi Documentation ✅
-
-**Before**: Summary files alongside main guides
-
-- `RASPBERRY_PI_OPTIMIZATIONS.md` - Main guide
-- `RASPBERRY_PI_COMPATIBILITY.md` - Main guide
-- `RPI5_OPTIMIZATIONS_SUMMARY.md` - Quick reference
-- `RPI5_ACTION_CHECKLIST.md` - Verification checklist
-
-**After**: Main comprehensive guides retained
-
-- `RASPBERRY_PI_OPTIMIZATIONS.md` - Complete optimization guide
-- `RASPBERRY_PI_COMPATIBILITY.md` - Complete compatibility guide
-
-**Archived**: 2 summary/checklist files moved to `docs/archive/`
-
-### 5. Minecraft Gameplay Documentation ✅
-
-**Before**: 2 separate files
-
-- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Enhancement roadmap
-- `GAMEPLAY_FEATURES_IMPLEMENTED.md` - Implementation summary
-
-**After**: 1 comprehensive file
-
-- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Complete guide with:
- - Current gameplay features
- - Recently implemented P1 features section
- - Future enhancement roadmap
-
-**Archived**: 1 file moved to `docs/archive/`
-
-### 6. Summary Files ✅
-
-**Archived**: Historical summary files
-
-- `SUMMARY.md` - Project analysis summary (info in CHANGELOG/ROADMAP)
-- `CONSOLIDATION_NOTES.md` - Historical consolidation notes
-
-## Files Archived
-
-Total: **17 files** in `docs/archive/`
-
-### CI/CD Related
-
-- `CI_CD_PIPELINE.md`
-- `CI_CD_OPTIMIZATIONS.md`
-- `CI_CD_ENHANCEMENTS.md`
-
-### API Related
-
-- `API_DOCUMENTATION.md`
-
-### Testing Related
-
-- `TESTING_COMPLETE.md`
-- `TESTING_FINAL_SUMMARY.md`
-- `TESTING_ENHANCEMENTS.md`
-
-### RPI Related
-
-- `RPI5_OPTIMIZATIONS_SUMMARY.md`
-- `RPI5_ACTION_CHECKLIST.md`
-
-### Minecraft Related
-
-- `GAMEPLAY_FEATURES_IMPLEMENTED.md`
-
-### Implementation Summaries
-
-- `IMPLEMENTATION_SUMMARY.md`
-- `IMPLEMENTATION_SUMMARY_P1.md`
-- `IMPLEMENTATION_SUMMARY_docs.md`
-- `FINAL_IMPLEMENTATION_SUMMARY.md`
-
-### Other
-
-- `SUMMARY.md`
-- `CONSOLIDATION_NOTES.md`
-- `README.md` (archive index)
-
-## Updated Files
-
-### Documentation Files
-
-- `CI_CD.md` - Completely rewritten with all content consolidated
-- `API.md` - Enhanced with OpenAPI specification details
-- `TESTING.md` - Enhanced with testing framework enhancements section
-- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Updated with implementation status
-- `INDEX.md` - Updated to reflect consolidated structure
-- `README.md` - Updated structure section
-
-### Archive Files
-
-- `archive/README.md` - Updated with list of all archived files
-
-## Benefits Achieved
-
-1. **Reduced Redundancy** ✅
-
- - Eliminated duplicate information
- - Single source of truth for each topic
-
-2. **Easier Navigation** ✅
-
- - Fewer files to search through
- - Clearer organization in INDEX.md
- - Better categorization
-
-3. **Better Organization** ✅
-
- - Comprehensive guides for major topics
- - Historical documents preserved in archive
- - Clear separation between active and archived docs
-
-4. **Improved Maintainability** ✅
-
- - Single file to update for each major topic
- - Less risk of information getting out of sync
- - Easier to keep documentation current
-
-5. **Historical Preservation** ✅
- - All archived files preserved for reference
- - Archive README documents what was consolidated
- - Can reference archived files if needed
-
-## Current Documentation Structure
-
-### Main Guides (Comprehensive)
-
-- `CI_CD.md` - CI/CD pipeline (consolidated)
-- `API.md` - REST API (consolidated)
-- `TESTING.md` - Testing framework (consolidated)
-- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Gameplay enhancements (updated)
-
-### Specialized Reference Guides (Kept Separate)
-
-- `TEST_COVERAGE.md` - Coverage analysis
-- `WEB_UI_TESTING.md` - Frontend testing
-- `ANALYTICS.md` - Analytics features
-
-### All Other Guides (Unchanged)
-
-- Installation, user guides, developer guides remain as-is
-
-## Navigation
-
-Use **[INDEX.md](INDEX.md)** as the starting point for all documentation. It provides:
-
-- Organized categories
-- Quick navigation links
-- Clear structure
-- Links to all active documentation
-
-## Future Maintenance
-
-When adding new documentation:
-
-1. **Check existing guides first** - Add to existing comprehensive guides when possible
-2. **Follow INDEX.md structure** - Place new docs in appropriate category
-3. **Update INDEX.md** - Add new documentation links
-4. **Avoid summary files** - Use CHANGELOG.md for implementation summaries
-5. **Keep guides comprehensive** - Prefer enhancing existing guides over creating new summary files
-
-## Questions?
-
-- See [INDEX.md](INDEX.md) for navigation
-- Check [archive/README.md](archive/README.md) for archived file information
-- Reference [CHANGELOG.md](../CHANGELOG.md) for version history
-
----
-
-**Consolidation Date**: 2025-01-27
-**Files Reduced**: ~60 → 43 active files (~28% reduction)
-**Files Archived**: 17 files
-**Status**: ✅ Complete
diff --git a/docs/CURSOR_CONFIGURATION.md b/docs/CURSOR_CONFIGURATION.md
index b22198c..95d50a0 100644
--- a/docs/CURSOR_CONFIGURATION.md
+++ b/docs/CURSOR_CONFIGURATION.md
@@ -14,18 +14,27 @@ Cursor IDE uses various configuration files to provide:
## Configuration Files
-### `.cursorrules`
+### AI assistant instructions
-**Purpose**: AI agent instructions for consistent development across sessions.
+**Source of truth**: [`AGENTS.md`](../AGENTS.md) in the project root. It defines the
+stack, commands, code standards, testing layout and conventions.
-**Location**: Project root
+Every editor-specific file is a thin pointer to it — edit `AGENTS.md`, never these:
-**Usage**: Automatically loaded by Cursor IDE to guide AI assistants.
-
-**See Also**: [AGENT_INSTRUCTIONS.md](../AGENT_INSTRUCTIONS.md)
+| File | Read by |
+| --- | --- |
+| `.cursor/rules/project.mdc` | Cursor (rules format, always applied) |
+| `.cursorrules` | Cursor (legacy format) |
+| `CLAUDE.md` | Claude Code — plus a few Claude-specific notes |
+| `.github/copilot-instructions.md` | GitHub Copilot (older setups; newer ones read `AGENTS.md` directly) |
+| `.clinerules` | Cline |
+| `.windsurfrules` | Windsurf |
---
+> **Note**: `.vscode/` is gitignored, so the files below are not in the repository —
+> they are per-developer. The sections describe what to put in them if you want them.
+
### `.vscode/settings.json`
**Purpose**: Workspace-specific editor settings for Cursor/VS Code.
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 016ecbd..8812c6e 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -75,7 +75,7 @@ bash -n manage.sh
bash -n start.sh
# Test docker-compose
-docker-compose config
+docker compose config
# Test server startup (requires Docker)
make build
@@ -102,7 +102,7 @@ make logs
- 2-space indentation
- Use environment variables
- Keep lines under 120 characters
-- Validate with `docker-compose config`
+- Validate with `docker compose config`
### Documentation
- Markdown format
diff --git a/docs/DOCKER_COMPOSE_FIX.md b/docs/DOCKER_COMPOSE_FIX.md
deleted file mode 100644
index d86b0aa..0000000
--- a/docs/DOCKER_COMPOSE_FIX.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Quick Fix: Docker Compose Installation Conflict
-
-## Prerequisites: Install Docker First
-
-**If you see `docker: command not found`**, you need to install Docker first:
-
-```bash
-# Install Docker
-curl -fsSL https://get.docker.com -o get-docker.sh
-sudo sh get-docker.sh
-sudo usermod -aG docker $USER
-rm get-docker.sh
-
-# IMPORTANT: Log out and back in for Docker permissions
-exit
-# Then SSH back in: ssh pi@docker-server.local
-
-# Verify Docker is installed
-docker --version
-docker compose version
-```
-
-After installing Docker, the `docker-compose-plugin` is automatically included, so you don't need to install `docker-compose` separately.
-
----
-
-## The Problem
-
-You're getting this error when trying to install `docker-compose`:
-
-```
-dpkg: error processing archive ... trying to overwrite '/usr/libexec/docker/cli-plugins/docker-compose',
-which is also in package docker-compose-plugin
-```
-
-## The Solution
-
-The `docker-compose-plugin` is already installed with your Docker installation. You don't need the standalone `docker-compose` package.
-
-### Quick Fix (Run These Commands)
-
-```bash
-# 1. Clean up the broken package state
-sudo apt-get remove --purge docker-compose
-sudo apt-get autoremove
-sudo apt-get autoclean
-
-# 2. Verify docker compose plugin works
-docker compose version
-
-# You should see something like:
-# Docker Compose version v2.40.3
-```
-
-### Use Docker Compose Plugin
-
-Instead of `docker-compose` (with hyphen), use `docker compose` (with space):
-
-```bash
-# Old way (standalone):
-docker-compose up -d
-
-# New way (plugin):
-docker compose up -d
-```
-
-### All Docker Compose Commands
-
-Replace all instances of `docker-compose` with `docker compose`:
-
-| Old Command | New Command |
-| ------------------------ | ------------------------ |
-| `docker-compose up` | `docker compose up` |
-| `docker-compose down` | `docker compose down` |
-| `docker-compose pull` | `docker compose pull` |
-| `docker-compose build` | `docker compose build` |
-| `docker-compose logs` | `docker compose logs` |
-| `docker-compose ps` | `docker compose ps` |
-| `docker-compose restart` | `docker compose restart` |
-
-### Update Systemd Services
-
-If you have any systemd service files using `docker-compose`, update them:
-
-```bash
-# Edit the service file
-sudo nano /etc/systemd/system/your-service.service
-
-# Change:
-ExecStart=/usr/bin/docker-compose up -d
-
-# To:
-ExecStart=/usr/bin/docker compose up -d
-```
-
-Then reload systemd:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl restart your-service.service
-```
-
-## Why This Happens
-
-Modern Docker installations (Docker Engine 20.10+) include Docker Compose as a plugin. The plugin is installed as part of the Docker package and provides the same functionality as the standalone `docker-compose` package, but integrated directly into Docker.
-
-The plugin approach is:
-
-- ✅ More integrated with Docker
-- ✅ Automatically updated with Docker
-- ✅ Better performance
-- ✅ Recommended by Docker
-
-## Verification
-
-After fixing, verify everything works:
-
-```bash
-# Check Docker Compose version
-docker compose version
-
-# Test with a simple command
-docker compose --help
-
-# If you have a docker-compose.yml, test it
-docker compose config
-```
-
-## Still Having Issues?
-
-If `docker compose version` doesn't work, the plugin might not be installed:
-
-```bash
-# Install the plugin
-sudo apt-get update
-sudo apt-get install -y docker-compose-plugin
-
-# Verify
-docker compose version
-```
-
-## Summary
-
-1. ✅ Remove broken `docker-compose` package
-2. ✅ Use `docker compose` (with space) instead of `docker-compose` (with hyphen)
-3. ✅ Update any systemd services or scripts
-4. ✅ You're all set!
diff --git a/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md b/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md
deleted file mode 100644
index 8050adf..0000000
--- a/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Documentation Consolidation Summary
-
-This document summarizes the documentation consolidation that has been completed to improve organization and reduce redundancy.
-
-## ✅ Completed Consolidations
-
-### 1. CI/CD Documentation
-
-- **Consolidated into**: `CI_CD.md`
-- **Merged files**:
- - `CI_CD_PIPELINE.md` - Pipeline structure details
- - `CI_CD_OPTIMIZATIONS.md` - Performance optimizations
- - `CI_CD_ENHANCEMENTS.md` - Testing enhancements in CI/CD
-- **Archived**: All three files moved to `docs/archive/`
-- **Result**: Single comprehensive CI/CD guide covering all aspects
-
-### 2. API Documentation
-
-- **Consolidated into**: `API.md`
-- **Merged files**:
- - `API_DOCUMENTATION.md` - OpenAPI specification and developer docs
-- **Archived**: `API_DOCUMENTATION.md`
-- **Result**: Single comprehensive API guide with both usage examples and OpenAPI specification details
-
-### 3. Testing Documentation
-
-- **Consolidated into**: `TESTING.md`
-- **Merged files**:
- - `TESTING_ENHANCEMENTS.md` - Testing framework enhancements
-- **Archived**:
- - `TESTING_COMPLETE.md` - Implementation summary
- - `TESTING_FINAL_SUMMARY.md` - Final summary
- - `TESTING_ENHANCEMENTS.md` - Framework enhancements (merged)
-- **Result**: Single comprehensive testing guide with enhancements section
-
-### 4. Raspberry Pi Documentation
-
-- **Archived files**:
- - `RPI5_OPTIMIZATIONS_SUMMARY.md` - Quick reference (redundant with main guide)
- - `RPI5_ACTION_CHECKLIST.md` - Verification checklist (information in compatibility guide)
-- **Result**: Main comprehensive guides remain (`RASPBERRY_PI_OPTIMIZATIONS.md`, `RASPBERRY_PI_COMPATIBILITY.md`)
-
-### 5. Minecraft Gameplay Documentation
-
-- **Updated**: `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md`
-- **Merged files**:
- - `GAMEPLAY_FEATURES_IMPLEMENTED.md` - Implementation summary
-- **Archived**: `GAMEPLAY_FEATURES_IMPLEMENTED.md`
-- **Result**: Single gameplay enhancements guide with implementation status included
-
-### 6. Summary Files
-
-- **Archived**:
- - `SUMMARY.md` - Project analysis summary (information in CHANGELOG and ROADMAP)
- - `CONSOLIDATION_NOTES.md` - Historical consolidation notes
-- **Result**: Information accessible through current documentation structure
-
-## Archive Directory
-
-All archived files are located in `docs/archive/`. See [archive/README.md](archive/README.md) for details.
-
-**Total files archived**: 11 files
-
-## Benefits Achieved
-
-1. **Reduced Redundancy** - Eliminated duplicate information across multiple files
-2. **Easier Navigation** - Fewer files to search through (reduced from ~60 to ~48 docs)
-3. **Better Organization** - Clearer structure with comprehensive guides
-4. **Maintainability** - Single source of truth for each topic
-5. **Historical Preservation** - Archived files preserved for reference
-
-## Current Documentation Structure
-
-### Main Guides (Consolidated)
-
-- `CI_CD.md` - Complete CI/CD pipeline guide
-- `API.md` - Complete REST API documentation
-- `TESTING.md` - Complete testing guide with enhancements
-- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Gameplay enhancements roadmap with implementation status
-
-### Reference Guides (Unchanged)
-
-- `TEST_COVERAGE.md` - Coverage analysis guide (kept separate as specialized reference)
-- `WEB_UI_TESTING.md` - Frontend testing guide (kept separate as specialized reference)
-- `ANALYTICS.md` - Analytics features guide (not a test doc, kept separate)
-
-## Files Removed from Active Docs
-
-The following files have been archived (accessible in `docs/archive/`):
-
-- CI/CD related: `CI_CD_PIPELINE.md`, `CI_CD_OPTIMIZATIONS.md`, `CI_CD_ENHANCEMENTS.md`
-- API related: `API_DOCUMENTATION.md`
-- Testing related: `TESTING_COMPLETE.md`, `TESTING_FINAL_SUMMARY.md`, `TESTING_ENHANCEMENTS.md`
-- RPI related: `RPI5_OPTIMIZATIONS_SUMMARY.md`, `RPI5_ACTION_CHECKLIST.md`
-- Minecraft related: `GAMEPLAY_FEATURES_IMPLEMENTED.md`
-- Summary files: `SUMMARY.md`, `CONSOLIDATION_NOTES.md`
-
-## Documentation Index Updated
-
-The [INDEX.md](INDEX.md) has been updated to:
-
-- Remove references to archived files
-- Add links to consolidated guides
-- Include note about archived documentation
-- Reflect current documentation structure
-
-## Future Maintenance
-
-When adding new documentation:
-
-1. **Check existing guides** - Add to existing comprehensive guides when possible
-2. **Use INDEX.md** - Follow the structure outlined in INDEX.md
-3. **Update INDEX.md** - Add new documentation to the appropriate section
-4. **Avoid summaries** - Use CHANGELOG.md for implementation summaries instead of separate files
-
----
-
-**Consolidation Date**: 2025-01-27
-**Status**: ✅ Complete
diff --git a/docs/INDEX.md b/docs/INDEX.md
index 90b6895..5e09746 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -1,225 +1,122 @@
# Documentation Index
-Complete guide to all project documentation, organized by category.
+Every guide in this project, grouped by what you are trying to do.
-## 📚 Quick Navigation
-
-- **[Getting Started](#getting-started)** - Installation and setup
-- **[User Guides](#user-guides)** - How to use features
-- **[Developer Guides](#developer-guides)** - Contributing and development
-- **[Reference](#reference)** - Quick references and examples
-- **[Configuration](#configuration)** - Configuration guides
-- **[Troubleshooting](#troubleshooting)** - Problem solving
+- [Getting Started](#getting-started)
+- [Deployment & Operations](#deployment--operations)
+- [Server Features](#server-features)
+- [API & Web Panel](#api--web-panel)
+- [Performance & Raspberry Pi](#performance--raspberry-pi)
+- [Development](#development)
+- [Reference & Troubleshooting](#reference--troubleshooting)
---
## Getting Started
-### Installation & Setup
-
-- **[RPI5_FULL_DEPLOYMENT.md](RPI5_FULL_DEPLOYMENT.md)** - Complete guide for deploying all components (Minecraft, API, Web) on Raspberry Pi 5
-- **[DOCKER_DEPLOYMENT_FLOW.md](DOCKER_DEPLOYMENT_FLOW.md)** - How Docker images are deployed from CI to Raspberry Pi
-- **[AUTO_DEPLOYMENT_SETUP.md](AUTO_DEPLOYMENT_SETUP.md)** - Step-by-step guide for automatic deployment setup
-- **[UPDATE_DOCKER_IMAGE.md](UPDATE_DOCKER_IMAGE.md)** - How to check, pull, and update to the latest Docker image
-- **[UPDATE_CODEBASE.md](UPDATE_CODEBASE.md)** - How to update the GitHub repository code on Raspberry Pi 5
-- **[API_VENV_SETUP.md](API_VENV_SETUP.md)** - How to set up and use Python virtual environment for API server
-- **[SYSTEM_OPTIMIZATIONS.md](SYSTEM_OPTIMIZATIONS.md)** - Comprehensive system and filesystem optimizations for Raspberry Pi 5
-- **[RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md)** - Raspberry Pi 5 compatibility guide and verification steps
-- **[RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md)** - Performance optimizations and enhancements for Raspberry Pi 5
-- **[DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md)** - Configure Raspberry Pi 5 to boot and automatically pull/run Docker images
-- **[INSTALL.md](INSTALL.md)** - Complete installation guide for Raspberry Pi 5
-- **[README.md](../README.md)** - Project overview and quick start
-
-### First Steps
+| Guide | What it covers |
+| --- | --- |
+| [INSTALL.md](INSTALL.md) | Full installation on a Raspberry Pi 5, start to finish |
+| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | One-page command cheat sheet |
+| [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) | Worked examples for every config file |
+| [MINECRAFT_SERVER_SETUP.md](MINECRAFT_SERVER_SETUP.md) | Getting the Minecraft server itself running with auto-start |
-1. Read [INSTALL.md](INSTALL.md) for installation
-2. Review [QUICK_REFERENCE.md](QUICK_REFERENCE.md) for common commands
-3. Check [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) for configuration
+New here? Read `INSTALL.md`, then keep `QUICK_REFERENCE.md` open.
---
-## User Guides
-
-### Core Features
-
-- **[BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md)** - Backup scheduling, retention, and monitoring
-- **[CLOUD_BACKUP.md](CLOUD_BACKUP.md)** - Cloud backup integration (R2, S3, B2)
-- **[UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md)** - Server updates and version management
-- **[PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md)** - Installing and managing plugins
-- **[MOD_SUPPORT.md](MOD_SUPPORT.md)** - Mod loader detection and mod pack installation
-- **[MINECRAFT_ENHANCEMENTS.md](MINECRAFT_ENHANCEMENTS.md)** - Minecraft-specific enhancements and configurations
-- **[MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md)** - Gameplay enhancement roadmap (includes implemented P1 features)
-- **[MINECRAFT_MANAGEMENT.md](MINECRAFT_MANAGEMENT.md)** - Minecraft server management tools and scripts
-- **[MULTI_WORLD.md](MULTI_WORLD.md)** - Managing multiple worlds
-- **[LOG_MANAGEMENT.md](LOG_MANAGEMENT.md)** - Log rotation, search, and analysis
-
-### Advanced Features
-
-- **[RCON.md](RCON.md)** - Remote Console (RCON) setup and usage
-- **[API.md](API.md)** - Complete REST API documentation (includes OpenAPI spec)
-- **[WEB_INTERFACE.md](WEB_INTERFACE.md)** - Web admin panel guide
-- **[RBAC.md](RBAC.md)** - Role-Based Access Control (RBAC) system
-- **[API_KEYS.md](API_KEYS.md)** - API key management and usage
-- **[DYNAMIC_DNS.md](DYNAMIC_DNS.md)** - Dynamic DNS integration (DuckDNS, No-IP, Cloudflare)
-- **[ANALYTICS.md](ANALYTICS.md)** - Analytics and monitoring capabilities
+## Deployment & Operations
+
+| Guide | What it covers |
+| --- | --- |
+| [RPI5_FULL_DEPLOYMENT.md](RPI5_FULL_DEPLOYMENT.md) | Deploying all components (server, API, web) together |
+| [DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md) | Pulling and running Docker images automatically at boot |
+| [DOCKER_DEPLOYMENT_FLOW.md](DOCKER_DEPLOYMENT_FLOW.md) | How an image gets from CI to the Pi |
+| [AUTO_DEPLOYMENT_SETUP.md](AUTO_DEPLOYMENT_SETUP.md) | Wiring up automatic deployment |
+| [UPDATE_DOCKER_IMAGE.md](UPDATE_DOCKER_IMAGE.md) | Checking for and pulling a newer image |
+| [UPDATE_CODEBASE.md](UPDATE_CODEBASE.md) | Updating the repository checkout on the Pi |
+| [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) | Minecraft version updates and compatibility checks |
+| [MULTI_ARCHITECTURE.md](MULTI_ARCHITECTURE.md) | Building images for arm64 and amd64 |
+| [BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md) | Backup scheduling, retention, health checks, metrics |
+| [CLOUD_BACKUP.md](CLOUD_BACKUP.md) | Offsite backups to Cloudflare R2, S3 or Backblaze B2 |
+| [LOG_MANAGEMENT.md](LOG_MANAGEMENT.md) | Log rotation, search and analysis |
+| [DYNAMIC_DNS.md](DYNAMIC_DNS.md) | Keeping a hostname pointed at a changing home IP |
+| [CLOUDFLARE_SETUP.md](CLOUDFLARE_SETUP.md) | Cloudflare DDNS configuration specifics |
---
-## Developer Guides
-
-### Development Setup
-
-- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Development environment setup and workflow
-- **[CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md)** - Cursor IDE configuration guide
-- **[LINTING.md](LINTING.md)** - Code linting and static analysis
-- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines
-
-### Project Planning
-
-- **[ROADMAP.md](ROADMAP.md)** - Development roadmap and future plans
-- **[TASKS.md](TASKS.md)** - Detailed task breakdown with priorities
+## Server Features
-### Workspace
-
-- **[WORKSPACE_ENHANCEMENTS.md](WORKSPACE_ENHANCEMENTS.md)** - Workspace optimizations summary
-- **[AGENT_INSTRUCTIONS.md](../AGENT_INSTRUCTIONS.md)** - AI agent instructions for consistency
+| Guide | What it covers |
+| --- | --- |
+| [MINECRAFT_MANAGEMENT.md](MINECRAFT_MANAGEMENT.md) | Whitelist, bans, ops, server properties, announcements |
+| [MINECRAFT_ENHANCEMENTS.md](MINECRAFT_ENHANCEMENTS.md) | Minecraft-specific tuning and configuration |
+| [MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) | Gameplay feature set and roadmap |
+| [MULTI_WORLD.md](MULTI_WORLD.md) | Creating, switching and backing up multiple worlds |
+| [PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md) | Installing and configuring Bukkit/Spigot/Paper plugins |
+| [MOD_SUPPORT.md](MOD_SUPPORT.md) | Mod loader detection and mod pack installation |
+| [RCON.md](RCON.md) | Remote console setup and usage |
+| [ANALYTICS.md](ANALYTICS.md) | Player and server analytics collection and reports |
---
-## Reference
-
-### Quick References
-
-- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command reference and cheat sheet
-- **[CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md)** - Configuration file examples
+## API & Web Panel
-### Testing & Code Quality
-
-- **[TESTING.md](TESTING.md)** - Complete testing guide with framework enhancements
-- **[TEST_COVERAGE.md](TEST_COVERAGE.md)** - Test coverage analysis and gap identification
-- **[WEB_UI_TESTING.md](WEB_UI_TESTING.md)** - Frontend testing guide
-- **[LINTING.md](LINTING.md)** - Code linting and static analysis guide
-- **[DOCKER_OPTIMIZATION.md](DOCKER_OPTIMIZATION.md)** - Docker image optimization guide
-- **[DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md)** - Configure Raspberry Pi 5 to boot and automatically pull/run Docker images
-- **[PERFORMANCE_BENCHMARKING.md](PERFORMANCE_BENCHMARKING.md)** - Performance benchmarking and regression testing
-- **[MULTI_ARCHITECTURE.md](MULTI_ARCHITECTURE.md)** - Multi-architecture build and deployment guide
-- **[CI_CD.md](CI_CD.md)** - Complete CI/CD pipeline guide (consolidated)
+| Guide | What it covers |
+| --- | --- |
+| [API.md](API.md) | Complete REST API reference (mirrors `api/openapi.yaml`) |
+| [API_VENV_SETUP.md](API_VENV_SETUP.md) | Python virtual environment for the API server |
+| [API_KEYS.md](API_KEYS.md) | Creating, scoping and rotating API keys |
+| [RBAC.md](RBAC.md) | Roles and permissions |
+| [OAUTH_SETUP.md](OAUTH_SETUP.md) | Google / Apple sign-in |
+| [WEB_INTERFACE.md](WEB_INTERFACE.md) | Using the React admin panel |
+| [SECURITY_HARDENING.md](SECURITY_HARDENING.md) | Hardening the API and the host |
---
-## Configuration
-
-### Configuration Files
+## Performance & Raspberry Pi
-- **[config/README.md](../config/README.md)** - Configuration directory structure
-- **[CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md)** - Example configurations
-
-### Environment Variables
-
-See [INSTALL.md](INSTALL.md) and [DEVELOPMENT.md](DEVELOPMENT.md) for environment variable setup.
+| Guide | What it covers |
+| --- | --- |
+| [RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md) | What works on which Pi, and how to verify |
+| [RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md) | Pi-specific tuning (memory, JVM, thermals) |
+| [SYSTEM_OPTIMIZATIONS.md](SYSTEM_OPTIMIZATIONS.md) | OS and filesystem tuning |
+| [DOCKER_OPTIMIZATION.md](DOCKER_OPTIMIZATION.md) | Image size, build caching, layer strategy |
+| [PERFORMANCE_BENCHMARKING.md](PERFORMANCE_BENCHMARKING.md) | Measuring and comparing performance |
---
-## Troubleshooting
-
-- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common problems and solutions
-- **[LOG_MANAGEMENT.md](LOG_MANAGEMENT.md)** - Log analysis and debugging
-
----
+## Development
-## Project Information
+| Guide | What it covers |
+| --- | --- |
+| [DEVELOPMENT.md](DEVELOPMENT.md) | Local setup and day-to-day workflow |
+| [TESTING.md](TESTING.md) | Test layout, how to run each suite, coverage |
+| [WEB_UI_TESTING.md](WEB_UI_TESTING.md) | Vitest, MSW and Playwright specifics for `web/` |
+| [LINTING.md](LINTING.md) | ShellCheck, ESLint, flake8, yamllint |
+| [CI_CD.md](CI_CD.md) | GitHub Actions pipeline and release process |
+| [CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md) | Cursor IDE setup |
+| [ROADMAP.md](ROADMAP.md) | Planned work, by phase |
+| [TASKS.md](TASKS.md) | Detailed task backlog |
-- **[CHANGELOG.md](../CHANGELOG.md)** - Version history and changes
-- **[LICENSE](../LICENSE)** - Project license
-- **[README.md](../README.md)** - Main project documentation
+AI assistants read [`../AGENTS.md`](../AGENTS.md) — the single source of truth for
+conventions. See also [`../CONTRIBUTING.md`](../CONTRIBUTING.md).
---
-## Documentation by Topic
+## Reference & Troubleshooting
-### Server Management
-
-- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Commands
-- [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) - Updates
-- [RCON.md](RCON.md) - Remote control
-
-### Data Management
-
-- [BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md) - Backups
-- [MULTI_WORLD.md](MULTI_WORLD.md) - Worlds
-- [LOG_MANAGEMENT.md](LOG_MANAGEMENT.md) - Logs
-
-### Extensions
-
-- [PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md) - Plugins
-- [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) - Server types
-
-### Development
-
-- [DEVELOPMENT.md](DEVELOPMENT.md) - Setup
-- [TESTING.md](TESTING.md) - Testing
-- [API.md](API.md) - API development
-
-### Integration
-
-- [API.md](API.md) - REST API
-- [WEB_INTERFACE.md](WEB_INTERFACE.md) - Web panel
-- [RCON.md](RCON.md) - RCON protocol
-- [RBAC.md](RBAC.md) - Role-based access control
-- [API_KEYS.md](API_KEYS.md) - API key management
-
----
-
-## Documentation Structure
-
-```
-docs/
-├── INDEX.md # This file - navigation hub
-├── INSTALL.md # Installation guide
-├── QUICK_REFERENCE.md # Command reference
-├── CONFIGURATION_EXAMPLES.md # Config examples
-├── TROUBLESHOOTING.md # Problem solving
-│
-├── User Guides/
-│ ├── BACKUP_AND_MONITORING.md
-│ ├── UPDATE_MANAGEMENT.md
-│ ├── PLUGIN_MANAGEMENT.md
-│ ├── MULTI_WORLD.md
-│ ├── LOG_MANAGEMENT.md
-│ ├── RCON.md
-│ ├── API.md
-│ ├── WEB_INTERFACE.md
-│ ├── RBAC.md
-│ └── API_KEYS.md
-│
-└── Developer Guides/
- ├── DEVELOPMENT.md
- ├── TESTING.md
- ├── ROADMAP.md
- ├── CURSOR_CONFIGURATION.md
- └── WORKSPACE_ENHANCEMENTS.md
-```
-
----
-
-## Getting Help
-
-1. **Check the documentation** - Start with [QUICK_REFERENCE.md](QUICK_REFERENCE.md) or [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
-2. **Search existing issues** - Check GitHub issues for similar problems
-3. **Ask for help** - Open a GitHub issue with:
- - What you're trying to do
- - What happened vs what you expected
- - Relevant log output
- - Your configuration
+| Guide | What it covers |
+| --- | --- |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Installation, startup, restart loops, connectivity, Docker, system issues |
+| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | Command cheat sheet |
+| [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) | Config file examples |
+| [../CHANGELOG.md](../CHANGELOG.md) | Version history |
---
-## Archived Documentation
-
-Some documentation files have been consolidated and archived. See [archive/README.md](archive/README.md) for details.
-
-**Note**: All information from archived files has been integrated into the current documentation structure.
-
----
+## Adding a Document
-**Last Updated**: 2025-01-27
+Add the file to `docs/`, then add a row to the right table above — an unlisted
+document will not be found. Historical "summary" or "implementation complete"
+write-ups do not belong here; that record lives in `CHANGELOG.md` and git history.
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 7308f54..59a7e2f 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -162,10 +162,10 @@ ls -la
```bash
# Make setup script executable
-chmod +x setup-rpi.sh
+chmod +x scripts/setup-rpi.sh
# Run setup script
-./setup-rpi.sh
+./scripts/setup-rpi.sh
```
The setup script will:
@@ -192,7 +192,7 @@ ssh pi@minecraft-server.local
# Verify Docker works without sudo
docker --version
-docker-compose --version
+docker compose --version
```
### Step 7: Configure Server (Optional)
@@ -220,17 +220,17 @@ Press `Ctrl+X`, then `Y`, then `Enter` to save changes.
cd ~/minecraft-server
# Make management script executable
-chmod +x manage.sh
+chmod +x scripts/manage.sh
# Start the server
-./manage.sh start
+./scripts/manage.sh start
```
### Monitor Startup
```bash
# View logs (Press Ctrl+C to exit)
-./manage.sh logs
+./scripts/manage.sh logs
```
First startup takes 5-10 minutes as it:
@@ -305,7 +305,7 @@ Share this IP with friends: `YOUR.PUBLIC.IP:25565`
### Check Server Status
```bash
-./manage.sh status
+./scripts/manage.sh status
```
Should show container as "Up".
@@ -332,7 +332,7 @@ docker stats minecraft-server
### Create First Backup
```bash
-./manage.sh backup
+./scripts/manage.sh backup
```
## Troubleshooting
@@ -347,7 +347,7 @@ sudo systemctl status docker
sudo systemctl start docker
# Check detailed error logs
-docker-compose logs
+docker compose logs
```
### Memory Issues
@@ -365,7 +365,7 @@ environment:
Then restart:
```bash
-./manage.sh restart
+./scripts/manage.sh restart
```
### Permission Errors
@@ -408,7 +408,7 @@ nmap -p 25565 localhost
If you encounter issues:
1. Check the Troubleshooting section above
-2. Review logs: `./manage.sh logs`
+2. Review logs: `./scripts/manage.sh logs`
3. Check system resources: `htop`
4. Open an issue on GitHub with:
- Description of the problem
diff --git a/docs/LINTING.md b/docs/LINTING.md
index c52f4d3..4144bb1 100644
--- a/docs/LINTING.md
+++ b/docs/LINTING.md
@@ -349,4 +349,4 @@ The project includes Cursor configuration in `docs/CURSOR_CONFIGURATION.md` with
- [Development Guide](DEVELOPMENT.md) - Development workflow
- [Testing Guide](TESTING.md) - Testing framework
- [Contributing Guide](../CONTRIBUTING.md) - Contribution guidelines
-- [Code Quality Standards](../AGENT_INSTRUCTIONS.md) - Code standards
+- [Code Quality Standards](../AGENTS.md) - Code standards
diff --git a/docs/LOG_MANAGEMENT.md b/docs/LOG_MANAGEMENT.md
index 7041659..5870b1c 100644
--- a/docs/LOG_MANAGEMENT.md
+++ b/docs/LOG_MANAGEMENT.md
@@ -19,19 +19,19 @@ The log management system provides:
**View recent logs**:
```bash
-./manage.sh logs
+./scripts/manage.sh logs
```
**Search logs**:
```bash
-./manage.sh logs-search "player joined"
+./scripts/manage.sh logs-search "player joined"
```
**Manage logs**:
```bash
-./manage.sh logs-manage all
+./scripts/manage.sh logs-manage all
```
## Log Management Commands
@@ -41,7 +41,7 @@ The log management system provides:
Index logs for faster searching:
```bash
-./manage.sh logs-manage index
+./scripts/manage.sh logs-manage index
```
This will:
@@ -62,7 +62,7 @@ This will:
Automatically detect errors and warnings:
```bash
-./manage.sh logs-manage errors
+./scripts/manage.sh logs-manage errors
```
This will:
@@ -84,7 +84,7 @@ This will:
Rotate and archive log files:
```bash
-./manage.sh logs-manage rotate
+./scripts/manage.sh logs-manage rotate
```
This will:
@@ -104,7 +104,7 @@ This will:
View log statistics:
```bash
-./manage.sh logs-manage stats
+./scripts/manage.sh logs-manage stats
```
Shows:
@@ -122,9 +122,9 @@ Shows:
Search for any term in logs:
```bash
-./manage.sh logs-search "error"
-./manage.sh logs-search "player joined"
-./manage.sh logs-search "crash"
+./scripts/manage.sh logs-search "error"
+./scripts/manage.sh logs-search "player joined"
+./scripts/manage.sh logs-search "crash"
```
### Advanced Search Options
@@ -132,35 +132,35 @@ Search for any term in logs:
**Case-sensitive search**:
```bash
-./manage.sh logs-search -c "Error"
+./scripts/manage.sh logs-search -c "Error"
```
**Limit results**:
```bash
-./manage.sh logs-search -n 20 "error"
+./scripts/manage.sh logs-search -n 20 "error"
# Show maximum 20 results
```
**Search by log level**:
```bash
-./manage.sh logs-search -l ERROR
-./manage.sh logs-search -l WARN
-./manage.sh logs-search -l INFO
+./scripts/manage.sh logs-search -l ERROR
+./scripts/manage.sh logs-search -l WARN
+./scripts/manage.sh logs-search -l INFO
```
**Search by date**:
```bash
-./manage.sh logs-search -d 2025-01-15 "crash"
+./scripts/manage.sh logs-search -d 2025-01-15 "crash"
# Search on specific date
```
**Search date range**:
```bash
-./manage.sh logs-search -r 2025-01-01 2025-01-31 "player"
+./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "player"
# Search entire month
```
@@ -169,25 +169,25 @@ Search for any term in logs:
**Find all player connections**:
```bash
-./manage.sh logs-search "joined the game"
+./scripts/manage.sh logs-search "joined the game"
```
**Find all errors in last week**:
```bash
-./manage.sh logs-search -r $(date -d "7 days ago" +%Y-%m-%d) $(date +%Y-%m-%d) -l ERROR
+./scripts/manage.sh logs-search -r $(date -d "7 days ago" +%Y-%m-%d) $(date +%Y-%m-%d) -l ERROR
```
**Find specific player activity**:
```bash
-./manage.sh logs-search "PlayerName"
+./scripts/manage.sh logs-search "PlayerName"
```
**Find server crashes**:
```bash
-./manage.sh logs-search "crash\|exception\|fatal"
+./scripts/manage.sh logs-search "crash\|exception\|fatal"
```
## Configuration
@@ -321,7 +321,7 @@ cat config/log-management.conf | grep LOG_ROTATION
**Manual rotation**:
```bash
-./manage.sh logs-manage rotate
+./scripts/manage.sh logs-manage rotate
```
### Search Returns No Results
@@ -329,7 +329,7 @@ cat config/log-management.conf | grep LOG_ROTATION
**Re-index logs**:
```bash
-./manage.sh logs-manage index
+./scripts/manage.sh logs-manage index
```
**Check log files exist**:
@@ -344,7 +344,7 @@ ls -lh logs/archive/
**Check log sizes**:
```bash
-./manage.sh logs-manage stats
+./scripts/manage.sh logs-manage stats
du -sh logs/
du -sh data/logs/
```
@@ -400,11 +400,11 @@ local error_patterns=(
```bash
# Export all errors
-./manage.sh logs-manage errors
+./scripts/manage.sh logs-manage errors
cat logs/errors_*.txt > all_errors.txt
# Export specific date range
-./manage.sh logs-search -r 2025-01-01 2025-01-31 "error" > january_errors.txt
+./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "error" > january_errors.txt
```
### Log Analysis Scripts
diff --git a/docs/MINECRAFT_MANAGEMENT.md b/docs/MINECRAFT_MANAGEMENT.md
index 8aea982..3b1a7e3 100644
--- a/docs/MINECRAFT_MANAGEMENT.md
+++ b/docs/MINECRAFT_MANAGEMENT.md
@@ -306,6 +306,6 @@ The server properties manager validates all property values:
- [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties)
- [Performance Tuning](RASPBERRY_PI_OPTIMIZATIONS.md)
-- [API Documentation](API_DOCUMENTATION.md)
+- [API Documentation](API.md)
- [Quick Reference](QUICK_REFERENCE.md)
diff --git a/docs/MINECRAFT_SERVER_SETUP.md b/docs/MINECRAFT_SERVER_SETUP.md
index 2eff78c..675e6b5 100644
--- a/docs/MINECRAFT_SERVER_SETUP.md
+++ b/docs/MINECRAFT_SERVER_SETUP.md
@@ -149,7 +149,7 @@ cd ~/minecraft-server
docker compose logs -f
# Or use the management script
-./manage.sh logs
+./scripts/manage.sh logs
```
Wait for "Done!" in the logs, which means the server is ready.
@@ -250,22 +250,22 @@ docker compose restart
cd ~/minecraft-server
# Make executable (if not already)
-chmod +x manage.sh
+chmod +x scripts/manage.sh
# Start
-./manage.sh start
+./scripts/manage.sh start
# Stop
-./manage.sh stop
+./scripts/manage.sh stop
# Status
-./manage.sh status
+./scripts/manage.sh status
# Logs
-./manage.sh logs
+./scripts/manage.sh logs
# Console (attach to server)
-./manage.sh console
+./scripts/manage.sh console
```
## Troubleshooting
diff --git a/docs/MOD_SUPPORT.md b/docs/MOD_SUPPORT.md
index 84cb031..aded93a 100644
--- a/docs/MOD_SUPPORT.md
+++ b/docs/MOD_SUPPORT.md
@@ -177,10 +177,10 @@ Install the mod pack:
# In your startup script
if ./scripts/mod-loader-detector.sh detect; then
echo "Mod loader detected, starting modded server..."
- ./manage.sh start
+ ./scripts/manage.sh start
else
echo "No mod loader detected, starting vanilla server..."
- ./manage.sh start
+ ./scripts/manage.sh start
fi
```
@@ -199,7 +199,7 @@ fi
```bash
# Always backup before installing mods
-./manage.sh backup
+./scripts/manage.sh backup
./scripts/mod-pack-installer.sh install-url https://example.com/mod.jar
```
diff --git a/docs/MULTI_ARCHITECTURE.md b/docs/MULTI_ARCHITECTURE.md
index 1ed0973..e8a07b1 100644
--- a/docs/MULTI_ARCHITECTURE.md
+++ b/docs/MULTI_ARCHITECTURE.md
@@ -161,8 +161,8 @@ The `openjdk:21-jdk-slim` image is multi-architecture and Docker will pull the c
```bash
# Standard setup (already ARM64)
-./setup-rpi.sh
-./manage.sh start
+./scripts/setup-rpi.sh
+./scripts/manage.sh start
```
### Raspberry Pi 4 (ARM32)
@@ -174,7 +174,7 @@ docker tag minecraft-server:latest-arm32 minecraft-server:latest
# Or build locally
./scripts/build-multiarch.sh arch arm32
-./manage.sh start
+./scripts/manage.sh start
```
### x86_64 Systems
@@ -186,7 +186,7 @@ docker tag minecraft-server:latest-amd64 minecraft-server:latest
# Or build locally
./scripts/build-multiarch.sh arch amd64
-./manage.sh start
+./scripts/manage.sh start
```
## Docker Compose Configuration
@@ -215,10 +215,10 @@ services:
```bash
# ARM64
-docker-compose -f docker-compose.yml -f docker-compose.arm64.yml up -d
+docker compose -f docker-compose.yml -f docker-compose.arm64.yml up -d
# AMD64
-docker-compose -f docker-compose.yml -f docker-compose.amd64.yml up -d
+docker compose -f docker-compose.yml -f docker-compose.amd64.yml up -d
```
## Registry Setup
diff --git a/docs/MULTI_WORLD.md b/docs/MULTI_WORLD.md
index 1de7967..b917485 100644
--- a/docs/MULTI_WORLD.md
+++ b/docs/MULTI_WORLD.md
@@ -18,26 +18,26 @@ The multi-world system allows you to:
### List Worlds
```bash
-./manage.sh worlds list
+./scripts/manage.sh worlds list
```
### Create a New World
```bash
# Create a normal world
-./manage.sh worlds create myworld
+./scripts/manage.sh worlds create myworld
# Create a flat world
-./manage.sh worlds create flatworld flat
+./scripts/manage.sh worlds create flatworld flat
# Create a world with a specific seed
-./manage.sh worlds create seededworld normal 12345
+./scripts/manage.sh worlds create seededworld normal 12345
```
### Switch Worlds
```bash
-./manage.sh worlds switch myworld
+./scripts/manage.sh worlds switch myworld
```
## World Management
@@ -47,7 +47,7 @@ The multi-world system allows you to:
Create a new world with specific settings:
```bash
-./manage.sh worlds create [type] [seed]
+./scripts/manage.sh worlds create [type] [seed]
```
**World Types**:
@@ -61,13 +61,13 @@ Create a new world with specific settings:
```bash
# Standard world
-./manage.sh worlds create survival
+./scripts/manage.sh worlds create survival
# Flat world for building
-./manage.sh worlds create creative flat
+./scripts/manage.sh worlds create creative flat
# World with seed
-./manage.sh worlds create adventure normal -1234567890
+./scripts/manage.sh worlds create adventure normal -1234567890
```
### Listing Worlds
@@ -75,7 +75,7 @@ Create a new world with specific settings:
View all available worlds:
```bash
-./manage.sh worlds list
+./scripts/manage.sh worlds list
```
Shows:
@@ -90,13 +90,13 @@ Shows:
Get detailed information about a world:
```bash
-./manage.sh worlds info
+./scripts/manage.sh worlds info
```
Or for the current world:
```bash
-./manage.sh worlds info
+./scripts/manage.sh worlds info
```
### Switching Worlds
@@ -104,7 +104,7 @@ Or for the current world:
Switch to a different world:
```bash
-./manage.sh worlds switch
+./scripts/manage.sh worlds switch
```
This will:
@@ -121,7 +121,7 @@ This will:
Delete a world (with automatic backup):
```bash
-./manage.sh worlds delete
+./scripts/manage.sh worlds delete
```
**Warning**: This permanently deletes the world. A backup is created before deletion.
@@ -147,7 +147,7 @@ CREATED=2025-01-15 10:30:00
Apply world-specific settings:
```bash
-./manage.sh worlds config
+./scripts/manage.sh worlds config
```
This applies:
@@ -171,17 +171,17 @@ When switching worlds, the system automatically:
Create a template from an existing world:
```bash
-./manage.sh worlds create-template [source-world]
+./scripts/manage.sh worlds create-template [source-world]
```
**Example**:
```bash
# Create template from current world
-./manage.sh worlds create-template mytemplate
+./scripts/manage.sh worlds create-template mytemplate
# Create template from specific world
-./manage.sh worlds create-template survival-template survival
+./scripts/manage.sh worlds create-template survival-template survival
```
Templates are stored in `config/world-templates/` and can be reused to create new worlds quickly.
@@ -191,13 +191,13 @@ Templates are stored in `config/world-templates/` and can be reused to create ne
Create a new world from a template:
```bash
-./manage.sh worlds from-template
+./scripts/manage.sh worlds from-template
```
**Example**:
```bash
-./manage.sh worlds from-template newworld survival-template
+./scripts/manage.sh worlds from-template newworld survival-template
```
This creates a new world with the same structure as the template (excluding player data).
@@ -209,13 +209,13 @@ This creates a new world with the same structure as the template (excluding play
Backup a specific world:
```bash
-./manage.sh worlds backup
+./scripts/manage.sh worlds backup
```
Or backup the current world:
```bash
-./manage.sh worlds backup
+./scripts/manage.sh worlds backup
```
Backups are stored in `backups/worlds/` with timestamps.
@@ -278,7 +278,7 @@ Add to crontab for automatic backups:
Monitor world sizes:
```bash
-./manage.sh worlds sizes
+./scripts/manage.sh worlds sizes
```
Shows:
@@ -300,7 +300,7 @@ Useful for:
Standard Minecraft world with varied terrain:
```bash
-./manage.sh worlds create myworld normal
+./scripts/manage.sh worlds create myworld normal
```
### Flat World
@@ -308,7 +308,7 @@ Standard Minecraft world with varied terrain:
Superflat world for building:
```bash
-./manage.sh worlds create flatworld flat
+./scripts/manage.sh worlds create flatworld flat
```
Configure in `server.properties`:
@@ -323,7 +323,7 @@ generator-settings={"layers":[{"block":"minecraft:bedrock","height":1},{"block":
Amplified terrain (requires more resources):
```bash
-./manage.sh worlds create amplifiedworld amplified
+./scripts/manage.sh worlds create amplifiedworld amplified
```
**Note**: Amplified worlds are resource-intensive and may not perform well on Raspberry Pi 5.
@@ -333,7 +333,7 @@ Amplified terrain (requires more resources):
Large biomes variant:
```bash
-./manage.sh worlds create largeworld large_biomes
+./scripts/manage.sh worlds create largeworld large_biomes
```
## Best Practices
@@ -352,8 +352,8 @@ Large biomes variant:
**Solutions**:
-1. Ensure server is stopped: `./manage.sh stop`
-2. Check world exists: `./manage.sh worlds list`
+1. Ensure server is stopped: `./scripts/manage.sh stop`
+2. Check world exists: `./scripts/manage.sh worlds list`
3. Verify server.properties is writable
4. Check world directory has `level.dat`
@@ -377,7 +377,7 @@ Large biomes variant:
1. Check disk space: `df -h`
2. Verify world directory exists
3. Check file permissions
-4. Try manual backup: `./manage.sh worlds backup `
+4. Try manual backup: `./scripts/manage.sh worlds backup `
### World Too Large
@@ -385,7 +385,7 @@ Large biomes variant:
**Solutions**:
-1. Monitor sizes: `./manage.sh worlds sizes`
+1. Monitor sizes: `./scripts/manage.sh worlds sizes`
2. Delete unused worlds
3. Use MCA Selector or similar tools to delete unused chunks
4. Consider using flat worlds for building
@@ -404,17 +404,17 @@ Run multiple servers with different worlds:
Move worlds between servers:
-1. Backup world: `./manage.sh worlds backup `
+1. Backup world: `./scripts/manage.sh worlds backup `
2. Copy backup file to new server
3. Extract backup: `tar -xzf world__*.tar.gz -C data/`
-4. Switch to world: `./manage.sh worlds switch `
+4. Switch to world: `./scripts/manage.sh worlds switch `
### World Cloning
Clone an existing world:
-1. Create template: `./manage.sh worlds create-template template `
-2. Create from template: `./manage.sh worlds from-template template`
+1. Create template: `./scripts/manage.sh worlds create-template template `
+2. Create from template: `./scripts/manage.sh worlds from-template template`
---
diff --git a/docs/OPTIMIZATION_COMPLETE.md b/docs/OPTIMIZATION_COMPLETE.md
deleted file mode 100644
index 4a2cafc..0000000
--- a/docs/OPTIMIZATION_COMPLETE.md
+++ /dev/null
@@ -1,156 +0,0 @@
-# Optimization Tasks - COMPLETE ✅
-
-All optimization opportunities have been successfully implemented!
-
-## 📋 Summary
-
-### Phase 1: Core Optimizations ✅
-
-- ✅ React Hook Extraction (`usePolling`, `useErrorHandler`, `useAutoDismiss`)
-- ✅ Component Optimizations (Dashboard, Players, Backups, Analytics, MetricsChart)
-- ✅ Security Hardening (Input validation, rate limiting, security headers)
-
-### Phase 2: Advanced Optimizations ✅
-
-- ✅ Route-Based Code Splitting (Lazy Loading)
-- ✅ Debouncing & Throttling Hooks
-- ✅ Virtual Scrolling Component
-- ✅ API Request Caching & Deduplication
-- ✅ Build Optimizations (Chunk Splitting)
-
-## 📊 Performance Improvements
-
-### Bundle Size
-
-- **Initial Bundle**: Reduced by ~60-70%
-- **Code Splitting**: Routes loaded on-demand
-- **Vendor Chunks**: Separated for better caching
-
-### Runtime Performance
-
-- **API Calls**: Reduced by ~40-50% with caching
-- **Rendering**: Virtual scrolling handles large lists
-- **Input Performance**: Debouncing reduces CPU usage by ~30%
-- **Memory Usage**: Constant with virtual scrolling
-
-### User Experience
-
-- ✅ Faster initial page load
-- ✅ Smoother interactions
-- ✅ Reduced server load
-- ✅ Better error handling
-
-## 📁 Files Created/Modified
-
-### New Files
-
-- `web/src/hooks/useDebounce.js` - Debounce hook
-- `web/src/hooks/useThrottle.js` - Throttle hook
-- `web/src/utils/apiCache.js` - API caching utility
-- `web/src/components/VirtualList.jsx` - Virtual scrolling component
-- `web/src/components/LazyRoute.jsx` - Lazy route wrapper
-- `docs/ADVANCED_OPTIMIZATIONS.md` - Advanced optimizations documentation
-- `docs/OPTIMIZATION_SUMMARY.md` - Optimization summary
-- `docs/SECURITY_HARDENING.md` - Security documentation
-
-### Modified Files
-
-- `web/src/App.jsx` - Lazy loading for all routes
-- `web/src/pages/Logs.jsx` - Debouncing + virtual scrolling
-- `web/src/services/api.js` - API caching + deduplication
-- `web/vite.config.js` - Build optimizations
-- `web/src/pages/Dashboard.jsx` - Optimized with hooks
-- `web/src/pages/Players.jsx` - Optimized with hooks
-- `web/src/pages/Backups.jsx` - Optimized with hooks
-- `web/src/pages/Analytics.jsx` - Optimized with hooks
-- `web/src/components/MetricsChart.jsx` - Memoized
-
-## 🎯 Key Features
-
-### 1. Route-Based Code Splitting
-
-```jsx
-const Dashboard = lazy(() => import('./pages/Dashboard'));
-
-
- }>
-
-
-;
-```
-
-### 2. API Caching Strategy
-
-- **Fast-changing** (status, metrics): 2-3 seconds
-- **Moderate-changing** (players, backups): 5-10 seconds
-- **Slow-changing** (worlds, plugins, config): 30 seconds
-- **Analytics**: 60 seconds
-- **Auto-invalidation**: On mutations
-
-### 3. Debouncing Search/Filter
-
-```jsx
-const debouncedFilter = useDebounce(filter, 300);
-const filteredLogs = useMemo(
- () => logs.filter(log => log.includes(debouncedFilter)),
- [logs, debouncedFilter]
-);
-```
-
-### 4. Virtual Scrolling
-
-```jsx
-}
- itemHeight={24}
- containerHeight={600}
- overscan={10}
-/>
-```
-
-## 🚀 Impact Summary
-
-### Developer Experience
-
-- ✅ Easier to add new features with reusable hooks
-- ✅ Consistent patterns across components
-- ✅ Less code to maintain (~200 lines saved)
-- ✅ Better code organization
-
-### User Experience
-
-- ✅ Faster response times
-- ✅ Smoother interactions
-- ✅ More reliable data updates
-- ✅ Better error messages
-
-### Code Quality
-
-- ✅ Reduced duplication (~70%)
-- ✅ Better organization
-- ✅ Easier to understand
-- ✅ More maintainable
-
-## 📚 Documentation
-
-All optimizations are documented in:
-
-- `docs/OPTIMIZATION_SUMMARY.md` - Core optimizations
-- `docs/ADVANCED_OPTIMIZATIONS.md` - Advanced techniques
-- `docs/SECURITY_HARDENING.md` - Security improvements
-
-## ✨ Next Steps (Optional Future Enhancements)
-
-1. **Service Worker**: Offline support and advanced caching
-2. **Web Workers**: Heavy computations off main thread
-3. **Image Optimization**: Lazy loading and format conversion
-4. **Prefetching**: Pre-load next likely routes
-5. **Request Queue**: Batch multiple requests
-6. **IndexedDB**: Persistent cache storage
-
----
-
-**Status**: ✅ ALL OPTIMIZATIONS COMPLETE
-**Date**: 2025-01-27
-**Impact**: High - Significant performance improvements across all metrics
diff --git a/docs/OPTIMIZATION_SUMMARY.md b/docs/OPTIMIZATION_SUMMARY.md
deleted file mode 100644
index 8743615..0000000
--- a/docs/OPTIMIZATION_SUMMARY.md
+++ /dev/null
@@ -1,202 +0,0 @@
-# Optimization Summary
-
-This document summarizes all optimization tasks performed to improve performance, code quality, and maintainability.
-
-## ✅ Completed Optimizations
-
-### 1. React Hook Extraction & Code Reusability
-
-**Created Reusable Hooks:**
-
-- **`usePolling`** (`web/src/hooks/usePolling.js`)
-
- - Centralizes polling logic with automatic cleanup
- - Provides loading, error, and data states
- - Prevents memory leaks with proper cleanup
- - Applied to: Dashboard, Players, Backups, Analytics
-
-- **`useErrorHandler`** (`web/src/hooks/useErrorHandler.js`)
-
- - Consistent error handling across components
- - Integrates with toast notifications
- - Reduces code duplication
-
-- **`useAutoDismiss`** (`web/src/hooks/useAutoDismiss.js`)
- - Auto-dismisses messages after a delay
- - Replaces repeated setTimeout patterns
- - Cleaner component code
-
-### 2. Component Optimizations
-
-#### Dashboard Component
-
-- ✅ Replaced manual polling with `usePolling` hook
-- ✅ Optimized with `useCallback` for function memoization
-- ✅ Centralized error handling
-- ✅ Reduced re-renders
-
-#### Players Component
-
-- ✅ Functional KICK button with confirmation
-- ✅ Uses `usePolling` hook
-- ✅ Proper error handling
-- ✅ Loading states during operations
-
-#### Backups Component
-
-- ✅ Replaced manual polling with `usePolling` hook
-- ✅ Replaced setTimeout message clearing with `useAutoDismiss`
-- ✅ Removed console.error statements
-- ✅ Optimized with `useCallback`
-- ✅ Cleaner error handling
-
-#### Analytics Component
-
-- ✅ Replaced manual setInterval with `usePolling` hook
-- ✅ Removed console.error statements
-- ✅ Optimized data fetching with `useCallback`
-- ✅ Better error handling
-
-#### MetricsChart Component
-
-- ✅ Added `React.memo` to prevent unnecessary re-renders
-- ✅ Used `useMemo` for expensive computations
-- ✅ Extracted `getStatusColor` function outside component
-- ✅ Memoized data array calculation
-
-### 3. Performance Improvements
-
-**Before Optimizations:**
-
-- Manual polling in multiple components
-- Repeated setTimeout patterns
-- Unnecessary re-renders
-- Console.log statements everywhere
-- No memoization
-
-**After Optimizations:**
-
-- ✅ Centralized polling with automatic cleanup
-- ✅ Reusable hooks reduce code duplication
-- ✅ Memoized expensive components
-- ✅ Reduced unnecessary re-renders
-- ✅ Cleaner, more maintainable code
-
-### 4. Code Quality Improvements
-
-- ✅ Removed ~50+ lines of duplicate code
-- ✅ Standardized error handling patterns
-- ✅ Consistent loading states
-- ✅ Better component organization
-- ✅ Improved code readability
-
-## 📊 Performance Metrics
-
-### Code Reduction
-
-- **Lines Saved**: ~150-200 lines by extracting common patterns
-- **Components Optimized**: 5 major components
-- **Hooks Created**: 3 reusable hooks
-- **Duplicate Code**: Reduced by ~70%
-
-### Runtime Performance
-
-- **Re-render Reduction**: ~30-40% fewer unnecessary re-renders
-- **Memory Leaks Prevented**: Automatic cleanup in all hooks
-- **Network Efficiency**: Consistent polling intervals, no duplicate requests
-
-### Bundle Size
-
-- **Impact**: Minimal (hooks are small utilities)
-- **Tree Shaking**: Enabled by default in Vite
-- **Code Splitting**: Ready for lazy loading implementation
-
-## 🔄 Remaining Optimization Opportunities
-
-### High Priority
-
-1. **Apply usePolling to More Components**
-
- - Worlds.jsx - Currently no polling
- - Plugins.jsx - Could benefit from polling
- - FileBrowser.jsx - Static but could refresh periodically
-
-2. **Route-based Code Splitting**
-
- - Implement React.lazy() for route components
- - Reduce initial bundle size
- - Faster initial page load
-
-3. **Search/Filter Debouncing**
- - Add debouncing to Logs filter
- - Add debouncing to search inputs
- - Reduce unnecessary API calls
-
-### Medium Priority
-
-4. **Virtual Scrolling**
-
- - For long lists (backups, logs, players)
- - Improve rendering performance
- - Better memory usage
-
-5. **Request Deduplication**
-
- - Prevent duplicate API calls
- - Cache responses for short periods
- - Reduce server load
-
-6. **Image Optimization**
- - Lazy load images
- - Optimize image formats
- - Use WebP where supported
-
-### Low Priority
-
-7. **Service Worker for Offline Support**
-
- - Cache API responses
- - Offline functionality
- - Background sync
-
-8. **Web Workers for Heavy Computations**
- - Analytics calculations
- - Log parsing
- - Data processing
-
-## 📝 Best Practices Established
-
-1. **Always use hooks for polling** - Never manual setInterval
-2. **Memoize expensive components** - Use React.memo and useMemo
-3. **Use useCallback for event handlers** - Prevent unnecessary re-renders
-4. **Extract common patterns to hooks** - Don't repeat yourself
-5. **Centralize error handling** - Use useErrorHandler hook
-6. **Auto-dismiss messages** - Use useAutoDismiss hook
-
-## 🎯 Impact Summary
-
-### Developer Experience
-
-- ✅ Easier to add new features with reusable hooks
-- ✅ Consistent patterns across components
-- ✅ Less code to maintain
-- ✅ Better testing (hooks can be tested independently)
-
-### User Experience
-
-- ✅ Faster response times
-- ✅ Smoother interactions
-- ✅ More reliable data updates
-- ✅ Better error messages
-
-### Code Quality
-
-- ✅ Reduced duplication
-- ✅ Better organization
-- ✅ Easier to understand
-- ✅ More maintainable
-
----
-
-**Last Updated**: 2025-01-27
-**Status**: ✅ Core optimizations complete
diff --git a/docs/PERFORMANCE_BENCHMARKING.md b/docs/PERFORMANCE_BENCHMARKING.md
index 2bfc8df..67e397c 100644
--- a/docs/PERFORMANCE_BENCHMARKING.md
+++ b/docs/PERFORMANCE_BENCHMARKING.md
@@ -53,7 +53,7 @@ Measures the time from server start command to server ready state.
**Measurement**:
-- Time from `docker-compose up` to server logs showing "Done"
+- Time from `docker compose up` to server logs showing "Done"
- Includes container startup, JVM initialization, and world loading
### TPS (Ticks Per Second)
diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md
index f894555..aeccf20 100644
--- a/docs/QUICK_REFERENCE.md
+++ b/docs/QUICK_REFERENCE.md
@@ -5,14 +5,14 @@
### Server Management
```bash
-./manage.sh start # Start server
-./manage.sh stop # Stop server
-./manage.sh restart # Restart server
-./manage.sh status # Check status
-./manage.sh logs # View logs
-./manage.sh backup # Create backup (with world save & verification)
-./manage.sh console # Attach to server console
-./manage.sh update # Update configuration from git
+./scripts/manage.sh start # Start server
+./scripts/manage.sh stop # Stop server
+./scripts/manage.sh restart # Restart server
+./scripts/manage.sh status # Check status
+./scripts/manage.sh logs # View logs
+./scripts/manage.sh backup # Create backup (with world save & verification)
+./scripts/manage.sh console # Attach to server console
+./scripts/manage.sh update # Update configuration from git
```
### Backup Management
@@ -35,11 +35,11 @@
### Docker Commands
```bash
-docker-compose up -d # Start in background
-docker-compose down # Stop and remove
-docker-compose ps # List containers
-docker-compose logs -f # Follow logs
-docker-compose restart # Restart services
+docker compose up -d # Start in background
+docker compose down # Stop and remove
+docker compose ps # List containers
+docker compose logs -f # Follow logs
+docker compose restart # Restart services
docker attach minecraft-server # Attach to console
```
@@ -173,16 +173,16 @@ nmap -p 25565 localhost
### Create Backup
```bash
-./manage.sh backup
+./scripts/manage.sh backup
# Stored in: ./backups/minecraft_backup_TIMESTAMP.tar.gz
```
### Restore Backup
```bash
-./manage.sh stop
+./scripts/manage.sh stop
tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/
-./manage.sh start
+./scripts/manage.sh start
```
### Automated Backups (Cron)
@@ -190,7 +190,7 @@ tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/
```bash
crontab -e
# Add line for daily backup at 3 AM:
-0 3 * * * cd ~/minecraft-server && ./manage.sh backup
+0 3 * * * cd ~/minecraft-server && ./scripts/manage.sh backup
```
## Troubleshooting Quick Fixes
@@ -199,8 +199,8 @@ crontab -e
```bash
sudo systemctl restart docker
-docker-compose down
-docker-compose up -d
+docker compose down
+docker compose up -d
```
### High Memory Usage
@@ -209,14 +209,14 @@ docker-compose up -d
# Reduce memory in docker-compose.yml
# Reduce view-distance in server.properties
# Restart server
-./manage.sh restart
+./scripts/manage.sh restart
```
### Connection Refused
```bash
# Check if server is running
-./manage.sh status
+./scripts/manage.sh status
# Check if port is open
sudo ufw allow 25565/tcp
@@ -245,7 +245,7 @@ docker system prune -a
```bash
cd ~/minecraft-server
git pull
-./manage.sh restart
+./scripts/manage.sh restart
```
### Update Minecraft Version
@@ -256,9 +256,9 @@ nano docker-compose.yml
# Change MINECRAFT_VERSION
# Rebuild and restart
-docker-compose down
+docker compose down
rm -rf data/*.jar # Remove old jar
-docker-compose up -d --build
+docker compose up -d --build
```
### Update Raspberry Pi OS
@@ -297,7 +297,7 @@ sudo ufw enable
htop
# Terminal 2: Server logs
-cd ~/minecraft-server && ./manage.sh logs
+cd ~/minecraft-server && ./scripts/manage.sh logs
# Terminal 3: Docker stats
docker stats minecraft-server
@@ -317,11 +317,11 @@ docker ps --filter "name=minecraft-server" --format "{{.Status}}"
| Problem | Solution |
| --------------------------- | --------------------------------------------------- |
-| Can't connect locally | Check if server is running: `./manage.sh status` |
+| Can't connect locally | Check if server is running: `./scripts/manage.sh status` |
| Can't connect from internet | Configure port forwarding on router |
| Low FPS/lag | Reduce view-distance and max-players |
| Out of memory | Lower MEMORY_MAX in docker-compose.yml |
-| Server crash on startup | Check logs: `./manage.sh logs` |
+| Server crash on startup | Check logs: `./scripts/manage.sh logs` |
| Permission denied | Run: `sudo chown -R $USER:$USER ~/minecraft-server` |
## Contact & Support
@@ -337,9 +337,9 @@ docker ps --filter "name=minecraft-server" --format "{{.Status}}"
1. Flash Raspberry Pi OS with Imager
2. SSH to Pi: `ssh pi@minecraft-server.local`
3. Clone repo: `git clone https://github.com/and3rn3t/minecraft.git minecraft-server`
-4. Run setup: `cd minecraft-server && ./setup-rpi.sh`
+4. Run setup: `cd minecraft-server && ./scripts/setup-rpi.sh`
5. Log out and back in
-6. Start server: `./manage.sh start`
+6. Start server: `./scripts/manage.sh start`
7. Connect: `minecraft-server.local:25565`
-**Emergency Stop:** `./manage.sh stop` or `docker-compose down`
+**Emergency Stop:** `./scripts/manage.sh stop` or `docker compose down`
diff --git a/docs/RASPBERRY_PI_COMPATIBILITY.md b/docs/RASPBERRY_PI_COMPATIBILITY.md
index e718eac..66451f0 100644
--- a/docs/RASPBERRY_PI_COMPATIBILITY.md
+++ b/docs/RASPBERRY_PI_COMPATIBILITY.md
@@ -76,7 +76,7 @@ When building on Raspberry Pi 5:
```bash
# Build directly on Pi (recommended)
-docker-compose build
+docker compose build
# Or specify platform explicitly
docker buildx build --platform linux/arm64 -t minecraft-server .
@@ -150,7 +150,7 @@ chmod +x scripts/setup-rpi.sh
./scripts/setup-rpi.sh
# 3. Build Docker image
-docker-compose build
+docker compose build
# 4. Start server
./scripts/manage.sh start
@@ -168,7 +168,7 @@ docker buildx create --name multiarch --use
docker buildx build --platform linux/arm64 -t minecraft-server:arm64 .
# Or with docker-compose
-docker-compose build --build-arg BUILDPLATFORM=linux/arm64
+docker compose build --build-arg BUILDPLATFORM=linux/arm64
```
**Action Required**: ⚠️ Document cross-platform building (optional)
@@ -195,7 +195,7 @@ Before deploying to Raspberry Pi 5:
- [ ] **Docker Ready**:
- [ ] Docker installed: `docker --version`
- - [ ] Docker Compose installed: `docker-compose --version`
+ - [ ] Docker Compose installed: `docker compose --version`
- [ ] User in docker group: `groups | grep docker`
### Deployment Testing
@@ -220,7 +220,7 @@ Before deploying to Raspberry Pi 5:
3. **Build Docker Image**:
```bash
- docker-compose build
+ docker compose build
# Should complete without errors
```
@@ -258,7 +258,7 @@ python3 -m pytest tests/api/ -v
bash -n scripts/*.sh
# Docker Compose validation
-docker-compose config
+docker compose config
```
## Performance Considerations
@@ -306,7 +306,7 @@ Raspberry Pi 5 has 4 cores. Optimize JVM flags in `scripts/start.sh`:
#### 1. Docker Build Fails
-**Symptoms**: `docker-compose build` fails with architecture errors
+**Symptoms**: `docker compose build` fails with architecture errors
**Solutions**:
@@ -362,7 +362,7 @@ npm install
```bash
# Check logs
-docker-compose logs
+docker compose logs
# Check architecture compatibility
docker inspect minecraft-server | grep Architecture
diff --git a/docs/RASPBERRY_PI_OPTIMIZATIONS.md b/docs/RASPBERRY_PI_OPTIMIZATIONS.md
index 0c56bc3..9ec4ed1 100644
--- a/docs/RASPBERRY_PI_OPTIMIZATIONS.md
+++ b/docs/RASPBERRY_PI_OPTIMIZATIONS.md
@@ -356,10 +356,10 @@ Use Docker build cache effectively:
```bash
# Build with cache
-docker-compose build --parallel
+docker compose build --parallel
# Or use BuildKit
-DOCKER_BUILDKIT=1 docker-compose build
+DOCKER_BUILDKIT=1 docker compose build
```
### Parallel Builds
diff --git a/docs/RBAC.md b/docs/RBAC.md
index b7dce1a..c9060bc 100644
--- a/docs/RBAC.md
+++ b/docs/RBAC.md
@@ -362,4 +362,4 @@ const admins = users.filter(u => u.role === 'admin');
- [API Documentation](API.md) - Complete API reference
- [Web Interface Guide](WEB_INTERFACE.md) - Web UI documentation
-- [Security Guide](SECURITY.md) - Security best practices
+- [Security Hardening](SECURITY_HARDENING.md) - Security best practices
diff --git a/docs/README.md b/docs/README.md
index f6a7297..facd400 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,94 +1,14 @@
-# Documentation Directory
+# Documentation
-This directory contains all project documentation organized by category.
+**[INDEX.md](INDEX.md) is the navigation hub** — every guide in this project is
+listed there, grouped by task.
-## 📚 Documentation Index
+Quick jumps:
-**Start here**: [INDEX.md](INDEX.md) - Complete navigation guide to all documentation
+- Installing for the first time → [INSTALL.md](INSTALL.md)
+- Looking up a command → [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+- Something is broken → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+- Working on the code → [DEVELOPMENT.md](DEVELOPMENT.md) and [../AGENTS.md](../AGENTS.md)
-## Structure
-
-```
-docs/
-├── INDEX.md # Navigation hub - start here!
-│
-├── Getting Started/
-│ ├── INSTALL.md # Installation guide
-│ └── QUICK_REFERENCE.md # Command reference
-│
-├── User Guides/
-│ ├── BACKUP_AND_MONITORING.md
-│ ├── UPDATE_MANAGEMENT.md
-│ ├── PLUGIN_MANAGEMENT.md
-│ ├── MULTI_WORLD.md
-│ ├── LOG_MANAGEMENT.md
-│ ├── RCON.md
-│ ├── API.md # Complete REST API guide
-│ ├── WEB_INTERFACE.md
-│ ├── RBAC.md
-│ ├── API_KEYS.md
-│ └── DYNAMIC_DNS.md
-│
-├── Developer Guides/
-│ ├── DEVELOPMENT.md
-│ ├── TESTING.md # Complete testing guide
-│ ├── CI_CD.md # Complete CI/CD guide
-│ ├── ROADMAP.md
-│ ├── CURSOR_CONFIGURATION.md
-│ └── WORKSPACE_ENHANCEMENTS.md
-│
-├── Reference/
-│ ├── CONFIGURATION_EXAMPLES.md
-│ ├── TROUBLESHOOTING.md
-│ ├── TEST_COVERAGE.md
-│ └── WEB_UI_TESTING.md
-│
-└── archive/ # Archived/superseded docs
- └── README.md # Archive index
-```
-
-## Quick Access
-
-### For Users
-
-- **New to the project?** → [INSTALL.md](INSTALL.md)
-- **Need a command?** → [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
-- **Having problems?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
-
-### For Developers
-
-- **Setting up dev environment?** → [DEVELOPMENT.md](DEVELOPMENT.md)
-- **Want to contribute?** → [../CONTRIBUTING.md](../CONTRIBUTING.md)
-- **Setting up Cursor IDE?** → [CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md)
-
-### For Planning
-
-- **What's next?** → [ROADMAP.md](ROADMAP.md)
-- **What needs doing?** → [TASKS.md](TASKS.md)
-- **What changed?** → [../CHANGELOG.md](../CHANGELOG.md)
-
-## Documentation Standards
-
-All documentation follows these standards:
-
-- Markdown format
-- Clear headings and structure
-- Code examples included
-- Links kept relative
-- Updated when features change
-
-## Contributing to Documentation
-
-When adding or updating documentation:
-
-1. Update [INDEX.md](INDEX.md) if adding new docs
-2. Follow existing documentation style
-3. Include code examples
-4. Update related documentation
-5. Update [CHANGELOG.md](../CHANGELOG.md) if user-facing
-
-## See Also
-
-- [Main README](../README.md) - Project overview
-- [Agent Instructions](../AGENT_INSTRUCTIONS.md) - AI agent guide
-- [Contributing Guide](../CONTRIBUTING.md) - How to contribute
+Adding a document? Put it in this directory and add a row to the matching table in
+[INDEX.md](INDEX.md), or nobody will find it.
diff --git a/docs/RESTART_LOOP_TROUBLESHOOTING.md b/docs/RESTART_LOOP_TROUBLESHOOTING.md
deleted file mode 100644
index 82c253e..0000000
--- a/docs/RESTART_LOOP_TROUBLESHOOTING.md
+++ /dev/null
@@ -1,251 +0,0 @@
-# Server Restart Loop Troubleshooting
-
-If your Minecraft server keeps restarting, follow these steps to diagnose and fix the issue.
-
-## Quick Diagnosis
-
-1. **Check container status**:
-
- ```bash
- docker ps -a | grep minecraft-server
- ```
-
-2. **View recent logs**:
-
- ```bash
- docker logs --tail 100 minecraft-server
- ```
-
-3. **Check restart count**:
-
- ```bash
- docker inspect minecraft-server | grep -A 5 RestartCount
- ```
-
-## Common Causes
-
-### 1. Out of Memory (OOM)
-
-**Symptoms**: Logs show `OutOfMemoryError` or container is killed by Docker
-
-**Solution**:
-
-- Reduce memory allocation in `docker-compose.yml`:
-
- ```yaml
- environment:
- - MEMORY_MIN=512M
- - MEMORY_MAX=1G
- ```
-
-- Check system memory:
-
- ```bash
- free -h
- ```
-
-### 2. Server JAR Missing or Corrupted
-
-**Symptoms**: "Could not find or load main class" or "Error: Unable to access jarfile"
-
-**Solution**:
-
-```bash
-# Stop server
-docker-compose down
-
-# Check if server.jar exists
-ls -lh data/server.jar
-
-# If missing, the start script will download it on next start
-# Or manually download:
-cd data
-wget -O server.jar https://piston-data.mojang.com/v1/objects/8dd1a28015f51b1803213892b50b7b4fc76e594d/server.jar
-```
-
-### 3. Port Already in Use
-
-**Symptoms**: "Address already in use" in logs
-
-**Solution**:
-
-```bash
-# Find what's using port 25565
-sudo netstat -tlnp | grep 25565
-# or
-sudo lsof -i :25565
-
-# Kill the process or change port in docker-compose.yml
-```
-
-### 4. Corrupted World Data
-
-**Symptoms**: Server crashes during world loading
-
-**Solution**:
-
-```bash
-# Stop server
-docker-compose down
-
-# Backup and remove corrupted world
-mv data/world data/world.backup.$(date +%Y%m%d)
-# Or delete if you don't need it:
-# rm -rf data/world
-
-# Restart
-docker-compose up -d
-```
-
-### 5. Healthcheck Failing
-
-**Symptoms**: Container restarts even though Java is running
-
-**Solution**:
-
-- Increase healthcheck start period in `docker-compose.yml`:
-
- ```yaml
- healthcheck:
- start_period: 180s # Give server more time to start
- retries: 5
- ```
-
-### 6. Disk Space Full
-
-**Symptoms**: "No space left on device" in logs
-
-**Solution**:
-
-```bash
-# Check disk space
-df -h
-
-# Clean up old backups/logs
-./scripts/log-manager.sh clean
-# Or manually:
-rm -rf backups/*.tar.gz
-rm -rf data/logs/*.log.gz
-```
-
-### 7. Insufficient Permissions
-
-**Symptoms**: Permission denied errors in logs
-
-**Solution**:
-
-```bash
-# Fix permissions
-sudo chown -R $USER:$USER data/ backups/ plugins/
-chmod -R 755 data/ backups/ plugins/
-```
-
-## Temporary Fix: Disable Auto-Restart
-
-To stop the restart loop temporarily and investigate:
-
-1. **Change restart policy**:
-
- ```yaml
- # In docker-compose.yml, change:
- restart: on-failure
- # to:
- restart: "no"
- ```
-
-2. **Restart container**:
-
- ```bash
- docker-compose up -d
- ```
-
-3. **Monitor logs**:
-
- ```bash
- docker logs -f minecraft-server
- ```
-
-4. **Once fixed, restore restart policy**:
-
- ```yaml
- restart: on-failure
- ```
-
-## Advanced Debugging
-
-### Enable Verbose Logging
-
-Add to `docker-compose.yml`:
-
-```yaml
-environment:
- - JAVA_OPTS=-Xlog:gc*:file=/minecraft/server/logs/gc.log -XX:+PrintGCDetails
-```
-
-### Check System Resources
-
-```bash
-# CPU and Memory usage
-docker stats minecraft-server
-
-# System temperature (Raspberry Pi)
-vcgencmd measure_temp
-vcgencmd get_throttled
-
-# Disk I/O
-iostat -x 1
-```
-
-### Check Java Process
-
-```bash
-# Inside container
-docker exec minecraft-server ps aux | grep java
-docker exec minecraft-server pgrep -f java
-
-# Check Java version
-docker exec minecraft-server java -version
-```
-
-## Prevention
-
-1. **Monitor logs regularly**:
-
- ```bash
- docker logs --tail 50 -f minecraft-server
- ```
-
-2. **Set appropriate memory limits** for your system
-
-3. **Enable log rotation** to prevent disk fill
-
-4. **Regular backups** before making changes
-
-5. **Test changes** in a separate environment first
-
-## Getting Help
-
-If the issue persists, collect this information:
-
-```bash
-# System info
-uname -a
-free -h
-df -h
-
-# Docker info
-docker version
-docker-compose version
-
-# Server logs (last 200 lines)
-docker logs --tail 200 minecraft-server > server-logs.txt
-
-# Container inspect
-docker inspect minecraft-server > container-info.json
-
-# Server configuration
-cat docker-compose.yml
-cat data/server.properties | head -20
-```
-
-Share these files when asking for help.
diff --git a/docs/SETUP_CHECKLIST.md b/docs/SETUP_CHECKLIST.md
deleted file mode 100644
index ad15e64..0000000
--- a/docs/SETUP_CHECKLIST.md
+++ /dev/null
@@ -1,313 +0,0 @@
-# Minecraft Server Setup Checklist
-
-Use this checklist to ensure your server is fully configured and ready to use.
-
-## ✅ Completed Setup
-
-- [x] Docker installed and working
-- [x] Docker Compose plugin configured
-- [x] Minecraft server container running
-- [x] Systemd service configured for auto-start
-- [x] API server running and accessible
-- [x] Web frontend running and accessible
-- [x] API key created
-- [x] Network access configured
-
-## 🔧 Recommended Configuration
-
-### 1. Server Properties Configuration
-
-Configure your server settings:
-
-```bash
-cd ~/minecraft-server
-
-# Edit server properties
-nano data/server.properties
-```
-
-**Key settings to configure:**
-
-```properties
-# Server Name
-motd=My Minecraft Server
-
-# Player Limits
-max-players=10
-
-# Game Settings
-difficulty=normal
-gamemode=survival
-pvp=true
-
-# Performance (adjust for your Pi)
-view-distance=10 # Lower = better performance (6-12)
-simulation-distance=8 # Lower = better performance (4-10)
-
-# Security
-white-list=false # Set to true to enable whitelist
-online-mode=true # Require Minecraft authentication
-spawn-protection=16 # Protected spawn radius
-
-# World Settings
-level-name=world
-level-seed= # Leave empty for random
-generate-structures=true
-```
-
-**After editing, restart:**
-
-```bash
-sudo systemctl restart minecraft.service
-```
-
-### 2. Memory Settings (Optimize for Your Pi)
-
-Check your Pi's RAM:
-
-```bash
-free -h
-```
-
-**For 4GB Pi:**
-
-```bash
-cd ~/minecraft-server
-nano docker-compose.yml
-```
-
-Change to:
-
-```yaml
-environment:
- - MEMORY_MIN=1G
- - MEMORY_MAX=2G
-```
-
-**For 8GB Pi:**
-
-```yaml
-environment:
- - MEMORY_MIN=2G
- - MEMORY_MAX=4G
-```
-
-Then restart:
-
-```bash
-cd ~/minecraft-server
-docker compose down
-docker compose up -d
-```
-
-### 3. Test Minecraft Server Connection
-
-**From your local network:**
-
-1. Open Minecraft
-2. Multiplayer → Add Server
-3. Server Address: `192.168.1.22:25565` (your Pi's IP)
-4. Click Done and join
-
-**Verify server is accessible:**
-
-```bash
-# Check if port is listening
-sudo netstat -tulpn | grep 25565
-
-# Check server logs
-cd ~/minecraft-server
-docker compose logs --tail 50
-```
-
-### 4. Port Forwarding (For External Access)
-
-To allow players outside your network:
-
-1. **Log into your router** (usually 192.168.1.1)
-2. **Find Port Forwarding settings**
-3. **Add rule:**
- - External Port: 25565
- - Internal Port: 25565
- - Internal IP: 192.168.1.22 (your Pi's IP)
- - Protocol: TCP
-4. **Save and apply**
-
-**Find your public IP:**
-
-```bash
-curl ifconfig.me
-```
-
-Share this IP with friends: `YOUR_PUBLIC_IP:25565`
-
-### 5. Configure Automatic Backups
-
-Set up automated backups:
-
-```bash
-cd ~/minecraft-server
-
-# Create backup schedule config
-nano config/backup-schedule.conf
-```
-
-Add:
-
-```
-SCHEDULE=daily
-TIME=03:00
-ENABLED=true
-```
-
-**Or use the backup script:**
-
-```bash
-# Manual backup
-./manage.sh backup
-
-# Install automated backup timer
-./scripts/install-backup-timer.sh
-```
-
-### 6. Firewall Configuration
-
-Ensure ports are open:
-
-```bash
-# Allow Minecraft port
-sudo ufw allow 25565/tcp
-
-# Allow API port (already done)
-sudo ufw allow 8080/tcp
-
-# Allow web frontend port (already done)
-sudo ufw allow 5173/tcp
-
-# Check status
-sudo ufw status
-```
-
-### 7. Optional: Install Plugins (Paper/Spigot)
-
-If you want plugins, switch to Paper:
-
-```bash
-cd ~/minecraft-server
-
-# Switch to Paper server
-./scripts/switch-server-type.sh paper
-
-# Restart server
-sudo systemctl restart minecraft.service
-
-# Install plugins
-./scripts/plugin-manager.sh install /path/to/plugin.jar
-```
-
-### 8. Optional: Configure RCON (Remote Console)
-
-Enable RCON for remote server management:
-
-```bash
-cd ~/minecraft-server
-
-# Setup RCON
-./scripts/rcon-setup.sh
-
-# Test RCON connection
-./scripts/rcon-client.sh "list"
-```
-
-### 9. Server Optimization
-
-**For better performance on Raspberry Pi 5:**
-
-```bash
-cd ~/minecraft-server
-
-# Run optimization script
-./scripts/optimize-rpi5.sh
-
-# Or manually optimize
-./scripts/performance-presets.sh balanced
-```
-
-### 10. Test Everything
-
-**Complete system test:**
-
-```bash
-cd ~/minecraft-server
-
-# 1. Check Minecraft server
-docker ps | grep minecraft
-docker compose logs --tail 20
-
-# 2. Check API server
-./scripts/api-server.sh status
-curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/api/status
-
-# 3. Check web frontend
-curl http://localhost:5173
-
-# 4. Test Minecraft connection
-# From another computer, try connecting to 192.168.1.22:25565
-```
-
-## 📋 Quick Configuration Summary
-
-**Essential settings to check:**
-
-1. ✅ Server name (motd in server.properties)
-2. ✅ Max players (max-players)
-3. ✅ Difficulty (difficulty)
-4. ✅ Memory limits (docker-compose.yml)
-5. ✅ View distance (view-distance in server.properties)
-6. ✅ Port forwarding (router settings)
-7. ✅ Firewall rules (ufw)
-
-## 🎮 Ready to Play!
-
-Once you've completed the checklist:
-
-1. **Local Network**: Players can connect using `192.168.1.22:25565`
-2. **External Network**: Players can connect using `YOUR_PUBLIC_IP:25565` (after port forwarding)
-3. **Web Interface**: Access at `http://192.168.1.22:5173`
-4. **API**: Available at `http://192.168.1.22:8080/api`
-
-## 🔍 Troubleshooting
-
-**Server won't start:**
-
-```bash
-docker compose logs
-sudo systemctl status minecraft.service
-```
-
-**Can't connect:**
-
-```bash
-# Check if server is running
-docker ps
-
-# Check if port is open
-sudo netstat -tulpn | grep 25565
-
-# Check firewall
-sudo ufw status
-```
-
-**Performance issues:**
-
-- Lower view-distance in server.properties
-- Reduce max-players
-- Check memory usage: `free -h`
-- Monitor server: `docker stats minecraft-server`
-
-## 📚 Additional Resources
-
-- [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties)
-- [Performance Optimization](docs/RASPBERRY_PI_OPTIMIZATIONS.md)
-- [Backup Management](docs/BACKUP_AND_MONITORING.md)
-- [Plugin Management](docs/PLUGIN_MANAGEMENT.md)
diff --git a/docs/TESTING.md b/docs/TESTING.md
index b91673d..3a8aca8 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -238,48 +238,38 @@ See `.github/workflows/tests.yml` for configuration.
## Test Coverage
-### Current Coverage
+Coverage is measured for the Python API with `coverage.py`, configured in
+`.coverage-config.ini`. The enforced threshold is **40%** (`fail_under`); raise it
+in that file as coverage grows. `scripts/check-coverage.sh` honours the same value
+via `COVERAGE_THRESHOLD`.
-- **API Endpoints**: 51% coverage
-- **Authentication**: ✅ Fully tested
-- **Error Handling**: ✅ Fully tested
-- **Health Checks**: ✅ Fully tested
+That filename is not one coverage.py discovers on its own, so every entry point
+passes it explicitly with `--cov-config` — `tests/api/pytest.ini`, the `Makefile`
+targets, CI, and the helper scripts. Run pytest from `tests/api` so the relative
+path resolves.
-### Coverage Goals
+### Running coverage
-- **Target**: 80%+ coverage for API
-- **Current**: ~60%+ coverage (increased from 51%)
-- **Priority**: Critical paths first
-- **Focus**: Authentication, error handling, core endpoints, configuration management
-
-### New Test Coverage (This Session)
-
-**Backend API Tests:**
-
-- Configuration file management endpoints (list, get, save, validate)
-- Backup restore and delete endpoints
-- User authentication endpoints (register, login, logout, me)
-- OAuth endpoints (get URL, link, unlink)
-
-**Frontend Component Tests:**
+```bash
+make coverage # pytest with term + HTML report
+make coverage-check # fail if below the threshold
+make coverage-gaps # list untested lines by file
+```
-- ConfigEditor component (rendering, editing, saving, error handling)
-- OAuthButtons component (Google/Apple buttons, popup handling, callbacks)
-- AuthContext (authentication state, login, register, logout)
-- Login page (form rendering, validation, error handling)
-- Register page (form rendering, password validation, error handling)
-- ConfigFiles page (file list, loading, error handling)
+Reports land in `htmlcov/` (open `htmlcov/index.html`), plus `coverage.json` and
+`coverage.xml` for tooling. CI publishes the same numbers on every run — treat
+that as the source of truth rather than any figure written into a document.
-### Viewing Coverage
+### What is covered
-```bash
-# Terminal report
-python -m pytest tests/api/ --cov=api --cov-report=term-missing
+- **Well covered**: authentication and API keys, RBAC, OAuth, backup management,
+ config-file endpoints, analytics endpoints, log streaming, `run_script`.
+- **Partially covered**: server control workflows, monitoring/metrics integration,
+ error and failure paths.
+- **Thin**: shell-script unit tests (`tests/unit/` covers only a few scripts) and
+ end-to-end workflows, several of which skip without a live server.
-# HTML report
-python -m pytest tests/api/ --cov=api --cov-report=html
-open htmlcov/index.html
-```
+Open gaps worth closing are tracked in [TASKS.md](TASKS.md) rather than duplicated here.
## Continuous Improvement
@@ -485,7 +475,6 @@ pytest -m "not slow"
- [pytest Documentation](https://docs.pytest.org/)
- [BATS Documentation](https://bats-core.readthedocs.io/)
-- [Test Coverage Guide](TEST_COVERAGE.md) - Detailed coverage analysis
- [Web UI Testing Guide](WEB_UI_TESTING.md) - Frontend testing guide
- [Coverage.py Documentation](https://coverage.readthedocs.io/)
- [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/)
diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md
deleted file mode 100644
index 6e91aaa..0000000
--- a/docs/TEST_COVERAGE.md
+++ /dev/null
@@ -1,320 +0,0 @@
-# Test Coverage Guide
-
-This document outlines the test coverage for the Minecraft Server Management project and identifies areas that need additional testing.
-
-## Current Test Coverage
-
-### ✅ Well Covered Areas
-
-1. **Authentication & Authorization**
-
- - User registration and login (`test_auth.py`)
- - API key management (`test_api.py`)
- - RBAC permissions (`test_rbac.py`)
- - OAuth integration (`test_oauth.py`)
-
-2. **Backup Management**
-
- - Backup creation and listing (`test_backup_management.py`)
- - Integration tests (`test-backup-system.sh`)
-
-3. **Configuration Files**
- - File retrieval and saving (`test_config_files.py`)
-
-### ⚠️ Partially Covered Areas
-
-1. **API Endpoints**
-
- - Most endpoints only test authentication requirements
- - Limited functional testing
- - Missing error handling tests
-
-2. **Server Control**
-
- - Basic start/stop/restart tests
- - Missing comprehensive workflow tests
-
-3. **Monitoring & Metrics**
- - Basic metrics endpoint tests
- - Missing integration with actual monitoring
-
-### ❌ Missing Coverage
-
-1. **Analytics System** (NEW - Just Added)
-
- - ✅ Analytics API endpoint tests (`test_analytics.py`)
- - ✅ Integration tests (`test-analytics.sh`)
- - ✅ E2E tests (`test-analytics-workflow.sh`)
- - ✅ Unit tests for collector (`test-analytics-collector.sh`)
- - ⚠️ Unit tests for processor (Python script)
-
-2. **End-to-End Workflows**
-
- - Most E2E tests are skipped/placeholder
- - Missing complete user journey tests
-
-3. **Web UI Components**
-
- - No React component tests
- - No UI integration tests
-
-4. **Script Unit Tests**
-
- - Missing tests for many management scripts
- - Limited coverage for error cases
-
-5. **Error Handling**
- - Limited edge case testing
- - Missing failure scenario tests
-
-## New Tests Added
-
-### Analytics Tests
-
-#### API Tests (`tests/api/test_analytics.py`)
-
-- ✅ Analytics collection endpoint
-- ✅ Report generation endpoint
-- ✅ Trends endpoint
-- ✅ Anomalies endpoint
-- ✅ Predictions endpoint
-- ✅ Player behavior endpoint
-- ✅ Custom report generation
-
-#### Integration Tests (`tests/integration/test-analytics.sh`)
-
-- ✅ Data collection workflow
-- ✅ Report generation
-- ✅ Anomaly detection
-- ✅ Data retention
-- ✅ End-to-end analytics workflow
-
-#### E2E Tests (`tests/e2e/test-analytics-workflow.sh`)
-
-- ✅ Complete API workflow
-- ✅ Data collection via API
-- ✅ Report retrieval via API
-- ✅ All analytics endpoints
-
-#### Unit Tests (`tests/unit/test-analytics-collector.sh`)
-
-- ✅ Script execution
-- ✅ File creation
-- ✅ JSON validation
-- ✅ Error handling
-
-### Comprehensive API Tests (`tests/api/test_api_comprehensive.py`)
-
-- ✅ Server control functional tests
-- ✅ Backup management functional tests
-- ✅ Metrics data retrieval
-- ✅ Config file operations
-- ✅ Error handling
-- ✅ Query parameter handling
-
-## Recommended Additional Tests
-
-### High Priority
-
-1. **Analytics Processor Unit Tests**
-
- ```python
- # tests/api/test_analytics_processor.py
- - Test trend calculation
- - Test anomaly detection algorithms
- - Test prediction algorithms
- - Test data loading and filtering
- ```
-
-2. **Web UI Component Tests**
-
- ```javascript
- // web/src/pages/__tests__/Analytics.test.jsx
- - Component rendering
- - Data fetching
- - User interactions
- - Error states
- ```
-
-3. **Complete E2E Workflows**
-
- ```bash
- # tests/e2e/test-complete-user-journey.sh
- - User registration → Login → Server management
- - Backup creation → Restore workflow
- - Analytics collection → Report generation → View dashboard
- ```
-
-4. **Error Handling Tests**
- ```python
- # tests/api/test_error_handling.py
- - Network failures
- - File system errors
- - Invalid input handling
- - Timeout scenarios
- ```
-
-### Medium Priority
-
-5. **Script Unit Tests**
-
- ```bash
- # tests/unit/test-plugin-manager.sh
- # tests/unit/test-world-manager.sh
- # tests/unit/test-backup-scheduler.sh
- - Script execution
- - Parameter validation
- - Error handling
- - Output validation
- ```
-
-6. **Performance Tests**
-
- ```python
- # tests/performance/test_api_performance.py
- - Response time benchmarks
- - Concurrent request handling
- - Memory usage under load
- ```
-
-7. **Security Tests**
- ```python
- # tests/security/test_security.py
- - SQL injection prevention
- - XSS prevention
- - CSRF protection
- - Authentication bypass attempts
- ```
-
-### Low Priority
-
-8. **Load Tests**
-
- ```python
- # tests/load/test_load.py
- - High concurrent user scenarios
- - Large data set handling
- - Resource exhaustion scenarios
- ```
-
-9. **Compatibility Tests**
- ```bash
- # tests/compatibility/test_versions.sh
- - Different Python versions
- - Different Docker versions
- - Different OS versions
- ```
-
-## Running Tests
-
-### All Tests
-
-```bash
-./scripts/run-tests.sh
-```
-
-### Specific Test Suites
-
-```bash
-# Analytics tests
-pytest tests/api/test_analytics.py -v
-
-# Integration tests
-bats tests/integration/test-analytics.sh
-
-# E2E tests
-bats tests/e2e/test-analytics-workflow.sh
-
-# Unit tests
-bats tests/unit/test-analytics-collector.sh
-```
-
-### With Coverage
-
-```bash
-# Python tests with coverage
-pytest tests/api/ --cov=api --cov-report=html
-
-# Check coverage threshold
-./scripts/check-coverage.sh check
-```
-
-## Coverage Goals
-
-### Current Status
-
-- **API Coverage**: ~60% (target: 70%+)
-- **Script Coverage**: ~40% (target: 60%+)
-- **E2E Coverage**: ~20% (target: 50%+)
-- **Overall Coverage**: ~51% (target: 60%+)
-
-### Priority Areas for Improvement
-
-1. **Analytics System**: 0% → 80%+ ✅ (Just completed)
-2. **API Endpoints**: 40% → 70%+ (In progress)
-3. **E2E Workflows**: 20% → 50%+ (Next priority)
-4. **Web UI**: 0% → 50%+ (Future)
-
-## Test Best Practices
-
-### Writing Tests
-
-1. **Follow AAA Pattern**
-
- - Arrange: Set up test data
- - Act: Execute the code
- - Assert: Verify results
-
-2. **Test Edge Cases**
-
- - Invalid input
- - Empty data
- - Missing files
- - Network failures
-
-3. **Mock External Dependencies**
-
- - Docker commands
- - File system operations
- - Network requests
-
-4. **Keep Tests Independent**
- - Each test should be standalone
- - Clean up after tests
- - Don't rely on test execution order
-
-### Test Organization
-
-```
-tests/
-├── api/ # API endpoint tests
-├── unit/ # Script unit tests
-├── integration/ # Integration tests
-├── e2e/ # End-to-end tests
-├── performance/ # Performance tests (future)
-├── security/ # Security tests (future)
-└── helpers/ # Test utilities
-```
-
-## Continuous Improvement
-
-### Regular Tasks
-
-1. **Weekly**: Review test coverage reports
-2. **Monthly**: Add tests for new features
-3. **Quarterly**: Audit and improve test quality
-4. **Before Release**: Ensure all critical paths are tested
-
-### Metrics to Track
-
-- Test coverage percentage
-- Number of tests
-- Test execution time
-- Flaky test rate
-- Test failure rate
-
-## See Also
-
-- [Testing Guide](TESTING.md)
-- [Analytics Documentation](ANALYTICS.md)
-- [API Documentation](API.md)
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 9e721c7..cb07dc5 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -35,7 +35,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on
3. **Run script with more verbose output**:
```bash
- bash -x ./setup-rpi.sh
+ bash -x ./scripts/setup-rpi.sh
```
4. **Check disk space**:
@@ -70,7 +70,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on
```bash
docker --version
- docker-compose --version
+ docker compose --version
```
### Permission Denied Errors
@@ -103,7 +103,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on
### Server Won't Start
-**Symptoms**: `./manage.sh start` fails or server exits immediately
+**Symptoms**: `./scripts/manage.sh start` fails or server exits immediately
**Diagnostic Steps**:
@@ -118,7 +118,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on
2. **View detailed logs**:
```bash
- docker-compose logs
+ docker compose logs
```
3. **Check for port conflicts**:
@@ -143,7 +143,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on
```bash
echo "eula=true" > ~/minecraft-server/eula.txt
-./manage.sh restart
+./scripts/manage.sh restart
```
#### Out of Memory
@@ -202,11 +202,60 @@ ports:
4. **Delete corrupted world**:
```bash
- ./manage.sh stop
+ ./scripts/manage.sh stop
rm -rf data/world*
- ./manage.sh start
+ ./scripts/manage.sh start
```
+### Server Restart Loop
+
+**Symptoms**: The container starts, stops, and starts again in a cycle.
+
+**Diagnosis**:
+
+```bash
+docker ps -a | grep minecraft-server # Container status
+docker logs --tail 100 minecraft-server # Recent logs
+docker inspect minecraft-server | grep -A 5 RestartCount
+```
+
+**Common causes and fixes**:
+
+1. **Out of memory** — logs show `OutOfMemoryError`, or Docker kills the container.
+ Lower `MEMORY_MIN`/`MEMORY_MAX` in `docker-compose.yml` and check `free -h`.
+
+2. **Server JAR missing or corrupted** — "Could not find or load main class" or
+ "Unable to access jarfile". Stop the server, check `ls -lh data/server.jar`;
+ the start script re-downloads it on the next start if it is absent.
+
+3. **Port already in use** — "Address already in use". Find the holder with
+ `sudo lsof -i :25565` and stop it, or change the port in `docker-compose.yml`.
+
+4. **Corrupted world data** — crashes during world loading. Stop the server and
+ move the world aside: `mv data/world data/world.backup.$(date +%Y%m%d)`.
+
+5. **Healthcheck failing** — the container restarts even though Java is running.
+ Raise `healthcheck.start_period` (e.g. `180s`) and `retries` in `docker-compose.yml`.
+
+6. **Disk full** — "No space left on device". Check `df -h` and run
+ `./scripts/log-manager.sh clean`.
+
+7. **Insufficient permissions** — permission denied in the logs. Run
+ `./scripts/fix-permissions.sh`, or
+ `sudo chown -R $USER:$USER data/ backups/ plugins/`.
+
+**Breaking the loop to investigate**: set `restart: "no"` in `docker-compose.yml`,
+run `docker compose up -d`, and watch `docker logs -f minecraft-server`. Restore
+`restart: on-failure` once the cause is fixed.
+
+**Deeper debugging**:
+
+```bash
+docker stats minecraft-server # CPU and memory
+vcgencmd measure_temp && vcgencmd get_throttled # Pi thermal state
+docker exec minecraft-server java -version # Java inside the container
+```
+
### Server Download Fails
**Symptoms**: "Failed to download Minecraft server jar"
@@ -241,14 +290,14 @@ ports:
1. **Verify server is running**:
```bash
- ./manage.sh status
+ ./scripts/manage.sh status
# Should show "Up"
```
2. **Check server logs**:
```bash
- ./manage.sh logs
+ ./scripts/manage.sh logs
# Look for "Done!" message
```
@@ -438,7 +487,7 @@ ports:
```bash
# Add to crontab for daily restart
- 0 4 * * * cd ~/minecraft-server && ./manage.sh restart
+ 0 4 * * * cd ~/minecraft-server && ./scripts/manage.sh restart
```
### High CPU Usage
@@ -480,17 +529,17 @@ ports:
1. **Remove old containers**:
```bash
- docker-compose down
+ docker compose down
docker rm minecraft-server
- docker-compose up -d
+ docker compose up -d
```
2. **Rebuild image**:
```bash
- docker-compose down
- docker-compose build --no-cache
- docker-compose up -d
+ docker compose down
+ docker compose build --no-cache
+ docker compose up -d
```
3. **Check Docker logs**:
@@ -499,6 +548,36 @@ ports:
docker logs minecraft-server
```
+### Docker Compose Plugin Conflict
+
+**Symptoms**: `apt` fails while installing `docker-compose`:
+
+```text
+dpkg: error processing archive ... trying to overwrite
+'/usr/libexec/docker/cli-plugins/docker-compose',
+which is also in package docker-compose-plugin
+```
+
+**Cause**: Docker Engine 20.10+ ships Compose as a plugin (`docker compose`,
+with a space). The standalone `docker-compose` package conflicts with it and is
+not needed.
+
+**Fix**:
+
+```bash
+sudo apt-get remove --purge docker-compose
+sudo apt-get autoremove && sudo apt-get autoclean
+docker compose version # should print v2.x
+```
+
+If `docker compose version` still fails, install the plugin:
+`sudo apt-get install -y docker-compose-plugin`.
+
+Use `docker compose ` everywhere — including in any systemd unit files
+you wrote by hand (`ExecStart=/usr/bin/docker compose up -d`), followed by
+`sudo systemctl daemon-reload`. The `Makefile` detects which form is available
+and uses the plugin when present.
+
### Docker Disk Space Full
**Symptoms**: "No space left on device"
@@ -568,9 +647,9 @@ ports:
2. **Restore from backup**:
```bash
- ./manage.sh stop
+ ./scripts/manage.sh stop
tar -xzf backups/minecraft_backup_*.tar.gz -C data/
- ./manage.sh start
+ ./scripts/manage.sh start
```
3. **Consider using SSD**:
@@ -626,42 +705,42 @@ ports:
**Basic log viewing**:
```bash
-./manage.sh logs
+./scripts/manage.sh logs
# Shows last 100 lines of server logs
```
**Search logs**:
```bash
-./manage.sh logs-search "error"
+./scripts/manage.sh logs-search "error"
# Search for "error" in logs
-./manage.sh logs-search -l ERROR
+./scripts/manage.sh logs-search -l ERROR
# Show all ERROR level messages
-./manage.sh logs-search -d 2025-01-15 "crash"
+./scripts/manage.sh logs-search -d 2025-01-15 "crash"
# Search for "crash" on specific date
-./manage.sh logs-search -r 2025-01-01 2025-01-31 "player joined"
+./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "player joined"
# Search date range
```
**Log management**:
```bash
-./manage.sh logs-manage all
+./scripts/manage.sh logs-manage all
# Run all log operations (rotate, index, errors, stats)
-./manage.sh logs-manage index
+./scripts/manage.sh logs-manage index
# Parse and index logs for faster searching
-./manage.sh logs-manage errors
+./scripts/manage.sh logs-manage errors
# Detect and report error patterns
-./manage.sh logs-manage rotate
+./scripts/manage.sh logs-manage rotate
# Rotate and archive old logs
-./manage.sh logs-manage stats
+./scripts/manage.sh logs-manage stats
# Show log statistics
```
@@ -679,7 +758,7 @@ Edit `config/log-management.conf` to configure:
```bash
# Manually rotate logs
-./manage.sh logs-manage rotate
+./scripts/manage.sh logs-manage rotate
# Or reduce retention period in config/log-management.conf
LOG_RETENTION_DAYS=7
@@ -689,20 +768,20 @@ LOG_RETENTION_DAYS=7
```bash
# Re-index logs
-./manage.sh logs-manage index
+./scripts/manage.sh logs-manage index
# Then search
-./manage.sh logs-search "your search term"
+./scripts/manage.sh logs-search "your search term"
```
**Too many errors detected**:
```bash
# View error summary
-./manage.sh logs-manage errors
+./scripts/manage.sh logs-manage errors
# Check specific error patterns
-./manage.sh logs-search -l ERROR
+./scripts/manage.sh logs-search -l ERROR
```
## Getting Additional Help
@@ -723,10 +802,10 @@ When asking for help, include:
2. **Server logs**:
```bash
- docker-compose logs > logs.txt
+ docker compose logs > logs.txt
# Or use log management
- ./manage.sh logs-manage errors > errors.txt
- ./manage.sh logs-search "error" > search_results.txt
+ ./scripts/manage.sh logs-manage errors > errors.txt
+ ./scripts/manage.sh logs-search "error" > search_results.txt
```
3. **Configuration**:
@@ -754,7 +833,7 @@ When asking for help, include:
### Best Practices
-1. **Regular backups**: `./manage.sh backup`
+1. **Regular backups**: `./scripts/manage.sh backup`
2. **Monitor resources**: `htop` and `docker stats`
3. **Keep system updated**: `sudo apt update && sudo apt upgrade`
4. **Use quality hardware**: Good SD card, proper cooling
diff --git a/docs/UPDATE_MANAGEMENT.md b/docs/UPDATE_MANAGEMENT.md
index d48d2b4..e376867 100644
--- a/docs/UPDATE_MANAGEMENT.md
+++ b/docs/UPDATE_MANAGEMENT.md
@@ -207,7 +207,7 @@ Set server type in `docker-compose.yml` or `.env`:
```yaml
environment:
- - SERVER_TYPE=paper # vanilla, paper, spigot, or fabric
+ - SERVER_TYPE=paper # vanilla, paper or fabric (spigot needs BuildTools)
```
Or in `.env`:
diff --git a/docs/WORKSPACE_ENHANCEMENTS.md b/docs/WORKSPACE_ENHANCEMENTS.md
deleted file mode 100644
index 2a06963..0000000
--- a/docs/WORKSPACE_ENHANCEMENTS.md
+++ /dev/null
@@ -1,219 +0,0 @@
-# Workspace Enhancements Summary
-
-This document summarizes all the enhancements made to optimize the development workspace.
-
-## New Files Created
-
-### Documentation
-- **ROADMAP.md** - Comprehensive development roadmap with phases and timelines
-- **TASKS.md** - Detailed task breakdown with priorities and assignments
-- **DEVELOPMENT.md** - Developer guide for contributing to the project
-- **WORKSPACE_ENHANCEMENTS.md** - This file
-
-### Configuration Files
-- **Makefile** - Convenient commands for server management
-- **.editorconfig** - Consistent code formatting across editors
-- **.pre-commit-config.yaml** - Pre-commit hooks for code quality
-- **.env.example** - Environment variable template (create manually if needed)
-
-### VS Code Configuration
-- **.vscode/settings.json** - Editor settings and file associations
-- **.vscode/extensions.json** - Recommended extensions
-- **.vscode/launch.json** - Debug configurations
-
-### CI/CD
-- **.github/workflows/ci.yml** - GitHub Actions CI pipeline
-
-### Directory Structure
-- **config/README.md** - Configuration directory documentation
-- **scripts/README.md** - Scripts directory documentation
-
-## Optimizations Made
-
-### docker-compose.yml Enhancements
-- ✅ Added environment variable support (from .env file)
-- ✅ Added healthcheck configuration
-- ✅ Added logging configuration with rotation
-- ✅ Added resource limits and reservations
-- ✅ Added custom network subnet configuration
-- ✅ Added hostname configuration
-- ✅ Made all settings configurable via environment variables
-
-### .gitignore Updates
-- ✅ Added .env file exclusion
-- ✅ Added config files exclusion (with exceptions)
-- ✅ Added Python/Node.js exclusions for future features
-- ✅ Added test coverage exclusions
-- ✅ Better organization and comments
-
-## New Features Available
-
-### Makefile Commands
-```bash
-make help # Show all available commands
-make install # Install dependencies
-make start # Start server
-make stop # Stop server
-make restart # Restart server
-make status # Check status
-make logs # View logs
-make backup # Create backup
-make console # Attach to console
-make build # Build Docker image
-make clean # Clean Docker resources
-make test # Run tests
-make shell # Open container shell
-make info # Show system information
-```
-
-### VS Code Integration
-- Automatic formatting on save
-- Shell script syntax checking
-- YAML validation
-- Docker integration
-- Markdown linting
-- Recommended extensions auto-install
-
-### Pre-commit Hooks
-- Trailing whitespace removal
-- End of file fixes
-- YAML/JSON validation
-- Large file checking
-- Merge conflict detection
-- Shell script linting (shellcheck)
-- Markdown linting
-
-### CI/CD Pipeline
-- Automated syntax checking
-- Docker Compose validation
-- Shell script validation
-- Runs on every push and PR
-
-## Environment Variables
-
-Create a `.env` file in the root directory with these variables:
-
-```bash
-# Minecraft Version
-MINECRAFT_VERSION=1.20.4
-
-# Memory Settings
-MEMORY_MIN=1G
-MEMORY_MAX=2G
-
-# Server Port
-SERVER_PORT=25565
-
-# EULA Acceptance
-EULA=TRUE
-
-# Server Type
-SERVER_TYPE=vanilla
-
-# Timezone
-TZ=UTC
-
-# Backup Settings
-BACKUP_RETENTION_DAYS=7
-BACKUP_SCHEDULE=daily
-BACKUP_TIME=03:00
-
-# Monitoring
-ENABLE_MONITORING=true
-MONITORING_PORT=9090
-
-# RCON Settings
-ENABLE_RCON=false
-RCON_PORT=25575
-RCON_PASSWORD=
-
-# Dynamic DNS
-DDNS_ENABLED=false
-DDNS_PROVIDER=duckdns
-DDNS_DOMAIN=
-DDNS_TOKEN=
-
-# Cloud Backup
-CLOUD_BACKUP_ENABLED=false
-CLOUD_BACKUP_PROVIDER=s3
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-AWS_BUCKET_NAME=
-AWS_REGION=us-east-1
-```
-
-## Next Steps
-
-1. **Create .env file**
- ```bash
- cp .env.example .env
- # Edit .env with your settings
- ```
-
-2. **Install pre-commit hooks** (optional)
- ```bash
- pip install pre-commit
- pre-commit install
- ```
-
-3. **Install VS Code extensions** (if using VS Code)
- - Open VS Code in the project
- - Install recommended extensions when prompted
-
-4. **Test the setup**
- ```bash
- make test
- make build
- ```
-
-5. **Start developing**
- - Review ROADMAP.md for planned features
- - Check TASKS.md for specific tasks
- - Read DEVELOPMENT.md for guidelines
-
-## Benefits
-
-### For Developers
-- Consistent code formatting
-- Automated quality checks
-- Better IDE integration
-- Clear development guidelines
-- Comprehensive roadmap
-
-### For Users
-- Easier configuration management
-- Better documentation
-- More reliable updates
-- Clearer project direction
-
-### For Maintainers
-- Automated testing
-- Code quality enforcement
-- Better organization
-- Easier contribution process
-
-## Migration Notes
-
-### Existing Installations
-No breaking changes! All enhancements are backward compatible:
-- Existing `docker-compose.yml` still works
-- Old `manage.sh` commands still work
-- New features are optional
-
-### Upgrading
-1. Pull latest changes
-2. Copy `.env.example` to `.env` (optional)
-3. Review new documentation
-4. Test with `make test`
-
-## Support
-
-For questions about workspace enhancements:
-- Check DEVELOPMENT.md
-- Review ROADMAP.md for context
-- Open a GitHub issue
-
----
-
-**Last Updated**: 2025-01-XX
-
diff --git a/docs/archive/API_DOCUMENTATION.md b/docs/archive/API_DOCUMENTATION.md
deleted file mode 100644
index 0573291..0000000
--- a/docs/archive/API_DOCUMENTATION.md
+++ /dev/null
@@ -1,327 +0,0 @@
-# API Documentation Guide
-
-This guide covers the REST API documentation for the Minecraft Server Management system.
-
-## Overview
-
-The API provides comprehensive endpoints for:
-
-- Server control (start, stop, restart, commands)
-- Backup management (create, list, restore, delete)
-- Player management
-- World and plugin management
-- Configuration file management
-- Monitoring and metrics
-- User authentication and authorization
-- API key management
-- Dynamic DNS management
-
-## OpenAPI Specification
-
-The API is documented using OpenAPI 3.0 specification:
-
-- **File**: `api/openapi.yaml`
-- **Format**: YAML
-- **Version**: 3.0.3
-
-## Viewing Documentation
-
-### Method 1: Swagger Editor (Online)
-
-1. Go to [Swagger Editor](https://editor.swagger.io/)
-2. Copy contents of `api/openapi.yaml`
-3. Paste into editor
-4. View interactive documentation
-
-### Method 2: Swagger UI (Docker)
-
-```bash
-# Serve with Docker
-docker run -d \
- --name swagger-ui \
- -p 8081:8080 \
- -e SWAGGER_JSON=/openapi.yaml \
- -v $(pwd)/api/openapi.yaml:/openapi.yaml:ro \
- swaggerapi/swagger-ui
-
-# Open in browser
-open http://localhost:8081
-```
-
-### Method 3: Using Script
-
-```bash
-# Serve API docs
-./scripts/serve-api-docs.sh
-
-# Or with custom port
-PORT=9000 ./scripts/serve-api-docs.sh
-```
-
-### Method 4: Redoc
-
-```bash
-# Serve with Redoc
-docker run -d \
- --name redoc \
- -p 8081:80 \
- -v $(pwd)/api/openapi.yaml:/usr/share/nginx/html/openapi.yaml:ro \
- redocly/redoc
-
-# Open in browser
-open http://localhost:8081
-```
-
-## API Base URL
-
-- **Local**: `http://localhost:8080`
-- **Raspberry Pi**: `http://minecraft-server.local:8080`
-- **Production**: `https://your-domain.com:8080`
-
-## Authentication
-
-The API supports three authentication methods:
-
-### 1. API Key (Recommended for Automation)
-
-```bash
-curl -H "X-API-Key: your-api-key" \
- http://localhost:8080/api/status
-```
-
-### 2. Bearer Token (JWT)
-
-```bash
-# Login to get token
-TOKEN=$(curl -X POST http://localhost:8080/api/auth/login \
- -H "Content-Type: application/json" \
- -d '{"username":"admin","password":"password"}' \
- | jq -r '.token')
-
-# Use token
-curl -H "Authorization: Bearer $TOKEN" \
- http://localhost:8080/api/status
-```
-
-### 3. Session Cookie
-
-```bash
-# Login (creates session)
-curl -X POST http://localhost:8080/api/auth/login \
- -H "Content-Type: application/json" \
- -d '{"username":"admin","password":"password"}' \
- -c cookies.txt
-
-# Use session
-curl -b cookies.txt http://localhost:8080/api/status
-```
-
-## Endpoint Categories
-
-### Health Check
-
-- `GET /api/health` - Check API health (no auth required)
-
-### Authentication
-
-- `POST /api/auth/register` - Register new user
-- `POST /api/auth/login` - Login user
-- `POST /api/auth/logout` - Logout user
-- `GET /api/auth/me` - Get current user
-
-### Server Control
-
-- `GET /api/status` - Get server status
-- `POST /api/server/start` - Start server
-- `POST /api/server/stop` - Stop server
-- `POST /api/server/restart` - Restart server
-- `POST /api/server/command` - Send server command
-
-### Backups
-
-- `POST /api/backup` - Create backup
-- `GET /api/backups` - List backups
-- `POST /api/backups/{filename}/restore` - Restore backup
-- `DELETE /api/backups/{filename}` - Delete backup
-
-### Players
-
-- `GET /api/players` - List players
-
-### Worlds
-
-- `GET /api/worlds` - List worlds
-
-### Plugins
-
-- `GET /api/plugins` - List plugins
-
-### Configuration
-
-- `GET /api/config/files` - List configuration files
-- `GET /api/config/files/{filename}` - Get configuration file
-- `POST /api/config/files/{filename}` - Update configuration file
-- `POST /api/config/files/{filename}/validate` - Validate configuration file
-
-### Logs
-
-- `GET /api/logs` - Get server logs
-
-### Metrics
-
-- `GET /api/metrics` - Get server metrics
-
-### API Keys
-
-- `GET /api/keys` - List API keys
-- `POST /api/keys` - Create API key
-- `DELETE /api/keys/{key_id}` - Delete API key
-- `PUT /api/keys/{key_id}/enable` - Enable API key
-- `PUT /api/keys/{key_id}/disable` - Disable API key
-
-### Users
-
-- `GET /api/users` - List users
-- `PUT /api/users/{username}/role` - Update user role
-- `DELETE /api/users/{username}` - Delete user
-- `PUT /api/users/{username}/enable` - Enable user
-- `PUT /api/users/{username}/disable` - Disable user
-
-### Dynamic DNS
-
-- `GET /api/ddns/status` - Get DDNS status
-- `POST /api/ddns/update` - Update DDNS
-- `GET /api/ddns/config` - Get DDNS configuration
-- `POST /api/ddns/config` - Update DDNS configuration
-
-## Example Requests
-
-### Start Server
-
-```bash
-curl -X POST http://localhost:8080/api/server/start \
- -H "X-API-Key: your-api-key" \
- -H "Content-Type: application/json"
-```
-
-### Create Backup
-
-```bash
-curl -X POST http://localhost:8080/api/backup \
- -H "X-API-Key: your-api-key" \
- -H "Content-Type: application/json"
-```
-
-### Get Server Status
-
-```bash
-curl http://localhost:8080/api/status \
- -H "X-API-Key: your-api-key"
-```
-
-### Send Server Command
-
-```bash
-curl -X POST http://localhost:8080/api/server/command \
- -H "X-API-Key: your-api-key" \
- -H "Content-Type: application/json" \
- -d '{"command": "say Hello from API"}'
-```
-
-### List Backups
-
-```bash
-curl http://localhost:8080/api/backups \
- -H "X-API-Key: your-api-key"
-```
-
-## Response Format
-
-### Success Response
-
-```json
-{
- "success": true,
- "message": "Operation completed",
- "data": { ... }
-}
-```
-
-### Error Response
-
-```json
-{
- "error": "Error message",
- "code": "ERROR_CODE"
-}
-```
-
-## Status Codes
-
-- `200` - Success
-- `201` - Created
-- `400` - Bad Request
-- `401` - Unauthorized
-- `403` - Forbidden
-- `404` - Not Found
-- `500` - Internal Server Error
-
-## Rate Limiting
-
-Currently no rate limiting is implemented. Consider implementing for production use.
-
-## CORS
-
-CORS is enabled for all origins. Configure in `config/api.conf` for production.
-
-## Updating Documentation
-
-When adding new endpoints:
-
-1. Update `api/openapi.yaml` with new endpoint
-2. Add request/response schemas
-3. Update this documentation
-4. Test with Swagger UI
-
-## Tools
-
-### Generate Client Libraries
-
-Use [OpenAPI Generator](https://openapi-generator.tech/):
-
-```bash
-# Generate Python client
-openapi-generator generate \
- -i api/openapi.yaml \
- -g python \
- -o clients/python
-
-# Generate JavaScript client
-openapi-generator generate \
- -i api/openapi.yaml \
- -g javascript \
- -o clients/javascript
-```
-
-### Validate Specification
-
-```bash
-# Install swagger-cli
-npm install -g @apidevtools/swagger-cli
-
-# Validate
-swagger-cli validate api/openapi.yaml
-```
-
-## Resources
-
-- [OpenAPI Specification](https://swagger.io/specification/)
-- [Swagger Editor](https://editor.swagger.io/)
-- [Swagger UI](https://swagger.io/tools/swagger-ui/)
-- [Redoc](https://redocly.com/docs/redoc/)
-
-## See Also
-
-- [API Guide](API.md) - Detailed API usage guide
-- [API Keys Guide](API_KEYS.md) - API key management
-- [RBAC Guide](RBAC.md) - Role-based access control
diff --git a/docs/archive/CI_CD_ENHANCEMENTS.md b/docs/archive/CI_CD_ENHANCEMENTS.md
deleted file mode 100644
index 2ce627e..0000000
--- a/docs/archive/CI_CD_ENHANCEMENTS.md
+++ /dev/null
@@ -1,288 +0,0 @@
-# CI/CD Testing Enhancements
-
-This document describes the testing framework enhancements integrated into the CI/CD pipeline.
-
-## Overview
-
-The CI/CD pipeline has been enhanced to leverage all the new testing framework capabilities, providing better test coverage, faster execution, and more comprehensive reporting.
-
-## Enhanced Python Tests Job
-
-The `python-tests` job in `.github/workflows/main.yml` now includes:
-
-### 1. Test Requirements Installation
-
-```yaml
-- name: Install dependencies
- run: |
- pip install --upgrade pip
- pip install -r api/requirements.txt
- pip install -r api/requirements-test.txt
-```
-
-Installs all testing dependencies including:
-
-- `pytest-xdist` for parallel execution
-- `pytest-mock` for enhanced mocking
-- `jsonschema` for contract testing
-- `pyyaml` for OpenAPI schema parsing
-
-### 2. Parallel Test Execution
-
-```yaml
-- name: Run API tests (parallel)
- run: |
- cd tests/api
- pytest -v -n auto \
- --cov=../../api \
- --cov-config=../../.coverage-config.ini \
- --cov-report=term-missing \
- --cov-report=html:htmlcov \
- --cov-report=json:coverage.json \
- --cov-report=xml:coverage.xml \
- -ra
-```
-
-**Features**:
-
-- `-n auto` - Automatically detects CPU count and runs tests in parallel
-- Multiple coverage report formats (HTML, JSON, XML)
-- Detailed test output with `-ra` (show all test info)
-
-**Benefits**:
-
-- Faster test execution (typically 2-4x faster)
-- Better resource utilization
-- Multiple report formats for different tools
-
-### 3. Performance Tests
-
-```yaml
-- name: Run performance tests
- run: |
- cd tests/api
- pytest -v -m performance || echo "Performance tests completed"
-```
-
-Runs all tests marked with `@pytest.mark.performance`:
-
-- Endpoint response time tests
-- Load testing
-- Throughput measurement
-
-**Note**: Uses `|| echo` to prevent job failure if performance tests have issues (non-blocking)
-
-### 4. Contract Tests
-
-```yaml
-- name: Run contract tests
- run: |
- cd tests/api
- pytest -v -m contract || echo "Contract tests completed"
-```
-
-Runs all tests marked with `@pytest.mark.contract`:
-
-- API response schema validation
-- Request schema validation
-- OpenAPI compliance checks
-
-**Note**: Non-blocking to allow CI to continue even if schema validation has issues
-
-### 5. Coverage Gap Analysis
-
-```yaml
-- name: Analyze coverage gaps
- run: |
- chmod +x scripts/analyze-coverage-gaps.sh
- ./scripts/analyze-coverage-gaps.sh analyze || echo "Coverage gap analysis completed"
-```
-
-Analyzes test coverage and identifies:
-
-- Files with coverage < 80%
-- Missing line numbers
-- Test improvement suggestions
-
-Generates `coverage-gaps.txt` report.
-
-### 6. Coverage Report Artifacts
-
-```yaml
-- name: Upload coverage reports
- uses: actions/upload-artifact@v4
- if: always()
- with:
- name: coverage-reports
- path: |
- coverage.json
- coverage.xml
- htmlcov/
- coverage-gaps.txt
- retention-days: 30
-```
-
-Uploads all coverage reports as GitHub Actions artifacts:
-
-- **coverage.json** - JSON format for programmatic access
-- **coverage.xml** - XML format for Codecov and other tools
-- **htmlcov/** - HTML report for visual inspection
-- **coverage-gaps.txt** - Gap analysis report
-
-**Access**: Download from GitHub Actions run page under "Artifacts"
-
-### 7. Codecov Integration
-
-```yaml
-- name: Upload coverage to Codecov
- uses: codecov/codecov-action@v4
- with:
- files: ./coverage.xml
- flags: unittests
- name: codecov-umbrella
- fail_ci_if_error: false
-```
-
-Uploads coverage to Codecov for:
-
-- Coverage tracking over time
-- PR coverage comments
-- Coverage badges
-- Coverage trends
-
-## Test Execution Flow
-
-```
-1. Install Dependencies
- ├── Production dependencies (api/requirements.txt)
- └── Test dependencies (api/requirements-test.txt)
-
-2. Run Main Test Suite (Parallel)
- ├── All unit tests
- ├── Integration tests
- └── Generate coverage reports
-
-3. Run Performance Tests
- └── Endpoint performance validation
-
-4. Run Contract Tests
- └── API schema validation
-
-5. Analyze Coverage Gaps
- └── Identify untested code
-
-6. Upload Artifacts
- ├── Coverage reports
- └── Gap analysis
-
-7. Upload to Codecov
- └── Coverage tracking
-```
-
-## Benefits
-
-### Speed Improvements
-
-- **Parallel Execution**: 2-4x faster test runs
-- **Efficient Resource Use**: Better CPU utilization
-- **Faster Feedback**: Quicker CI results
-
-### Better Coverage
-
-- **Multiple Report Formats**: HTML for humans, JSON/XML for tools
-- **Gap Analysis**: Identifies areas needing tests
-- **Codecov Integration**: Track coverage trends
-
-### Quality Assurance
-
-- **Performance Tests**: Catch performance regressions
-- **Contract Tests**: Ensure API compliance
-- **Comprehensive Reporting**: Multiple views of test results
-
-## Accessing Results
-
-### Coverage Reports
-
-1. Go to GitHub Actions run page
-2. Click on "python-tests" job
-3. Download "coverage-reports" artifact
-4. Extract and open `htmlcov/index.html` in browser
-
-### Coverage Gaps
-
-1. Download "coverage-reports" artifact
-2. Open `coverage-gaps.txt` to see:
- - Files with low coverage
- - Missing line numbers
- - Improvement suggestions
-
-### Codecov Dashboard
-
-1. Visit Codecov dashboard (if configured)
-2. View coverage trends
-3. See PR coverage comments
-4. Track coverage over time
-
-## Configuration
-
-### Test Markers
-
-Tests are organized using pytest markers:
-
-- `@pytest.mark.unit` - Unit tests
-- `@pytest.mark.integration` - Integration tests
-- `@pytest.mark.api` - API endpoint tests
-- `@pytest.mark.performance` - Performance tests
-- `@pytest.mark.contract` - Contract tests
-- `@pytest.mark.slow` - Slow running tests
-
-### Coverage Threshold
-
-Configured in `.coverage-config.ini`:
-
-- Minimum coverage: 60%
-- Target coverage: 80%
-
-### Parallel Execution
-
-- **Auto-detection**: `-n auto` uses all available CPUs
-- **Manual**: Can specify `-n 4` for 4 workers
-- **Optimal**: Usually 2-4x CPU count works best
-
-## Troubleshooting
-
-### Tests Failing in CI
-
-1. Check test output in GitHub Actions
-2. Download coverage reports artifact
-3. Review coverage-gaps.txt for missing tests
-4. Check performance test thresholds
-
-### Coverage Not Uploading
-
-1. Verify `coverage.xml` is generated
-2. Check Codecov token is configured
-3. Review Codecov action logs
-
-### Performance Tests Failing
-
-1. Check if thresholds are too strict
-2. Review performance test output
-3. Consider adjusting timeout values
-
-## Future Enhancements
-
-Potential future improvements:
-
-1. **Test Result Caching**: Cache test results for faster runs
-2. **Matrix Testing**: Test on multiple Python versions
-3. **Coverage Badges**: Auto-update coverage badges
-4. **PR Comments**: Auto-comment coverage on PRs
-5. **Performance Baselines**: Track performance over time
-
-## Resources
-
-- [GitHub Actions Documentation](https://docs.github.com/en/actions)
-- [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/)
-- [Codecov Documentation](https://docs.codecov.com/)
-- [Testing Enhancements Guide](../docs/TESTING_ENHANCEMENTS.md)
diff --git a/docs/archive/CI_CD_OPTIMIZATIONS.md b/docs/archive/CI_CD_OPTIMIZATIONS.md
deleted file mode 100644
index e85ac07..0000000
--- a/docs/archive/CI_CD_OPTIMIZATIONS.md
+++ /dev/null
@@ -1,261 +0,0 @@
-# CI/CD Pipeline Optimizations
-
-This document describes the optimizations implemented in the CI/CD pipeline to ensure clean and quick operations.
-
-## Overview
-
-The pipeline has been optimized for:
-- **Speed**: Reduced build times through caching and parallelization
-- **Reliability**: Better error handling and resource management
-- **Efficiency**: Reduced resource usage and costs
-- **Maintainability**: Cleaner, more organized workflow
-
-## Implemented Optimizations
-
-### 1. Dependency Caching
-
-#### Python Dependencies
-- **Implementation**: Uses GitHub Actions built-in pip caching
-- **Benefit**: Avoids re-downloading Python packages on every run
-- **Location**: `python-tests` job
-- **Cache Key**: Based on `api/requirements.txt` hash
-
-```yaml
-- name: Set up Python
- uses: actions/setup-python@v4
- with:
- python-version: '3.9'
- cache: 'pip'
- cache-dependency-path: api/requirements.txt
-```
-
-#### Node.js Dependencies
-- **Implementation**: Uses GitHub Actions built-in npm caching
-- **Benefit**: Faster frontend test execution
-- **Location**: `frontend-tests` and `playwright-tests` jobs
-- **Cache Key**: Based on `web/package-lock.json` hash
-
-#### BATS Installation
-- **Implementation**: Custom cache for BATS binary
-- **Benefit**: Skips BATS installation when cached
-- **Location**: `bash-tests` job
-- **Cache Key**: `bats-${{ runner.os }}-v1`
-
-#### APT Packages
-- **Implementation**: Caches `/var/cache/apt` directory
-- **Benefit**: Faster package installation in image builds
-- **Location**: `build-rpi-image` job
-- **Cache Key**: `apt-${{ runner.os }}-rpi-build-tools`
-
-#### Raspberry Pi OS Base Image
-- **Implementation**: Caches downloaded and extracted base image
-- **Benefit**: Skips 5-15 minute download on cache hits
-- **Location**: `build-rpi-image` job
-- **Cache Key**: `rpi-os-lite-2024-01-11-arm64`
-- **Note**: Cache key should be updated when base image version changes
-
-### 2. Docker Build Optimizations
-
-#### Build Cache
-- **Implementation**: GitHub Actions cache for Docker layers
-- **Benefit**: Reuses layers from previous builds
-- **Cache Scope**: `build-docker` to isolate cache per job
-- **Mode**: `max` for maximum cache utilization
-
-```yaml
-cache-from: type=gha,scope=build-docker
-cache-to: type=gha,mode=max,scope=build-docker
-```
-
-#### Build Context
-- **Implementation**: `.dockerignore` file excludes unnecessary files
-- **Benefit**: Smaller build context = faster uploads
-- **Excluded**: Documentation, tests, web frontend, CI/CD files
-
-### 3. Image Build Optimizations
-
-#### Reduced Wait Times
-- **Before**: 3 seconds wait after partition operations
-- **After**: 1 second wait with timeout-based verification
-- **Benefit**: Faster image customization step
-
-```bash
-# Optimized partition waiting
-sleep 1
-sudo partprobe $LOOP_DEVICE
-sleep 1
-
-# Timeout-based verification
-timeout=10
-while [ $timeout -gt 0 ] && [ ! -e "${LOOP_DEVICE}p1" ]; do
- sleep 0.5
- timeout=$((timeout - 1))
-done
-```
-
-#### Compression Optimization
-- **Before**: `xz -9` (maximum compression, slow)
-- **After**: `xz -6` (good compression, faster)
-- **Benefit**: 2-3x faster compression with minimal size increase
-- **Trade-off**: ~5-10% larger compressed file, but much faster
-
-#### Artifact Optimization
-- **Implementation**: Only upload compressed `.img.xz` files
-- **Benefit**: Smaller artifacts, faster uploads
-- **Compression Level**: 6 (balanced)
-
-### 4. Job Parallelization
-
-#### Current Structure
-- Lint, Python tests, and Bash tests run in parallel
-- Frontend and Playwright tests run in parallel (non-blocking)
-- Docker build waits for critical tests
-- Image build waits for Docker build
-
-#### Optimization Opportunities
-- All test jobs can run in parallel (already implemented)
-- Non-blocking tests don't block critical path
-- Summary job aggregates all results
-
-### 5. Resource Management
-
-#### Timeouts
-- **Image Build**: 120 minutes timeout
-- **Playwright Tests**: 60 minutes timeout
-- **Benefit**: Prevents hanging jobs from consuming resources
-
-#### APT Package Installation
-- **Optimization**: `--no-install-recommends` flag
-- **Benefit**: Installs only essential packages, faster installation
-
-### 6. Error Handling
-
-#### Image Verification
-- **Implementation**: Verify base image exists after extraction
-- **Benefit**: Fails fast if extraction fails
-
-#### Artifact Upload
-- **Implementation**: `if-no-files-found: error`
-- **Benefit**: Fails if expected artifacts are missing
-
-## Performance Improvements
-
-### Estimated Time Savings
-
-| Optimization | Time Saved | Frequency |
-|-------------|------------|-----------|
-| Python pip cache | 30-60s | Every run |
-| Node.js cache | 20-40s | Every run |
-| BATS cache | 10-20s | Every run |
-| APT cache | 15-30s | Image builds |
-| RPi OS image cache | 5-15 min | Image builds (cache hits) |
-| Compression optimization | 2-5 min | Image builds |
-| Reduced wait times | 4-6s | Image builds |
-| **Total (typical run)** | **1-2 min** | Every run |
-| **Total (image build)** | **7-20 min** | Image builds |
-
-### Cache Hit Rates
-
-- **Python/Node caches**: ~95% hit rate (changes only when dependencies update)
-- **BATS cache**: ~100% hit rate (rarely changes)
-- **APT cache**: ~80% hit rate (changes with workflow updates)
-- **RPi OS image cache**: ~50% hit rate (changes with base image updates)
-
-## Best Practices
-
-### 1. Cache Key Management
-
-- Use stable cache keys for rarely-changing dependencies
-- Include version numbers in cache keys for base images
-- Use hash-based keys for frequently-changing dependencies
-
-### 2. Compression Trade-offs
-
-- Use `-6` for xz compression (good balance)
-- Use `-9` only if file size is critical
-- Consider gzip for faster compression if size isn't critical
-
-### 3. Timeout Settings
-
-- Set appropriate timeouts for long-running jobs
-- Use shorter timeouts for quick operations
-- Monitor job durations and adjust as needed
-
-### 4. Dependency Updates
-
-- Update cache keys when dependency versions change
-- Clear caches if builds become inconsistent
-- Monitor cache sizes and clean up old caches
-
-## Future Optimization Opportunities
-
-### 1. Matrix Builds
-- Test on multiple Python versions (3.9, 3.10, 3.11)
-- Test on multiple Node.js versions (18, 20, 22)
-- **Benefit**: Better compatibility testing
-
-### 2. Larger Runners
-- Use `ubuntu-latest-4-cores` for image builds
-- **Benefit**: Faster compression and operations
-- **Cost**: Higher runner costs
-
-### 3. Parallel Image Operations
-- Mount and customize in parallel where possible
-- **Benefit**: Faster image customization
-
-### 4. Incremental Builds
-- Only rebuild changed components
-- **Benefit**: Faster builds for small changes
-
-### 5. Docker Layer Optimization
-- Further optimize Dockerfile layer ordering
-- **Benefit**: Better cache utilization
-
-## Monitoring
-
-### Key Metrics to Track
-
-1. **Job Duration**: Monitor average job times
-2. **Cache Hit Rates**: Track cache effectiveness
-3. **Resource Usage**: Monitor runner resource consumption
-4. **Failure Rates**: Track job failure frequency
-5. **Cost**: Monitor GitHub Actions minutes used
-
-### Tools
-
-- GitHub Actions analytics dashboard
-- Workflow run summaries
-- Cache usage statistics
-
-## Troubleshooting
-
-### Cache Issues
-
-**Problem**: Cache not being used
-- **Solution**: Check cache key matches
-- **Solution**: Verify cache path is correct
-- **Solution**: Check cache size limits
-
-**Problem**: Stale cache causing failures
-- **Solution**: Update cache key
-- **Solution**: Clear cache manually
-- **Solution**: Add cache version to key
-
-### Performance Issues
-
-**Problem**: Slow builds
-- **Solution**: Check cache hit rates
-- **Solution**: Verify optimizations are applied
-- **Solution**: Consider larger runners
-
-**Problem**: Timeouts
-- **Solution**: Increase timeout values
-- **Solution**: Optimize slow operations
-- **Solution**: Split long-running jobs
-
-## References
-
-- [GitHub Actions Caching](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
-- [Docker Build Cache](https://docs.docker.com/build/cache/)
-- [XZ Compression Options](https://tukaani.org/xz/manual/xz.html)
-
diff --git a/docs/archive/CI_CD_PIPELINE.md b/docs/archive/CI_CD_PIPELINE.md
deleted file mode 100644
index 44efb3b..0000000
--- a/docs/archive/CI_CD_PIPELINE.md
+++ /dev/null
@@ -1,243 +0,0 @@
-# CI/CD Pipeline Documentation
-
-## Overview
-
-The unified CI/CD pipeline (`main.yml`) combines all testing, building, and deployment workflows into a single comprehensive pipeline.
-
-## Pipeline Structure
-
-### Jobs Overview
-
-1. **Lint** - Syntax and validation checks (blocking)
-2. **Python Tests** - API tests (blocking)
-3. **Bash Tests** - Shell script tests (blocking)
-4. **Frontend Tests** - Vitest unit tests (non-blocking)
-5. **Playwright Tests** - E2E browser tests (non-blocking)
-6. **Build Docker** - Docker image build (blocking)
-7. **Build RPi Image** - Raspberry Pi image creation (conditional)
-8. **Summary** - Pipeline status summary
-
-### Job Dependencies
-
-```
-lint ──┐
- ├──> build-docker ──> build-rpi-image
-python-tests ──┘
-bash-tests ───┘
-
-frontend-tests (parallel, non-blocking)
-playwright-tests (parallel, non-blocking)
-
-All jobs ──> summary
-```
-
-## Non-Blocking Tests
-
-### Frontend Tests
-
-- **Status**: Non-blocking (`continue-on-error: true`)
-- **Purpose**: Unit tests for React components
-- **Failure Impact**: Pipeline continues, failure is reported in summary
-
-### Playwright Tests
-
-- **Status**: Non-blocking (`continue-on-error: true`)
-- **Purpose**: End-to-end browser automation tests
-- **Timeout**: 60 minutes
-- **Failure Impact**: Pipeline continues, test report uploaded as artifact
-- **Artifacts**: Playwright HTML report (retained for 30 days)
-
-## Raspberry Pi Image Building
-
-### When Images Are Built
-
-Images are automatically built when:
-
-- Pushing to `main` branch
-- Manual workflow dispatch with `build_image: true`
-- Creating a release tag
-
-### Image Contents
-
-The generated `.img` file includes:
-
-1. **Base System**: Raspberry Pi OS Lite (64-bit)
-2. **Pre-configured Services**:
- - SSH enabled
- - Hostname: `minecraft-server`
- - WiFi configuration (optional)
-3. **First-Boot Script**:
- - Updates system packages
- - Installs Docker and Docker Compose
- - Installs Node.js for web interface
- - Clones repository
- - Runs setup script
- - Configures Minecraft server
-
-### Image Specifications
-
-- **Format**: Compressed `.img.xz` file
-- **Size**: ~4GB (expandable on first boot)
-- **Architecture**: ARM64 (Raspberry Pi 5)
-- **Base OS**: Raspberry Pi OS Lite (Bookworm)
-
-### Using the Image
-
-1. **Download** the `.img.xz` file from:
-
- - Workflow artifacts (for main branch builds)
- - GitHub Releases (for tagged releases)
-
-2. **Extract** the image:
-
- ```bash
- xz -d minecraft-server-rpi5-YYYYMMDD.img.xz
- ```
-
-3. **Flash** to microSD card:
-
- ```bash
- # On Linux/macOS
- sudo dd if=minecraft-server-rpi5-YYYYMMDD.img of=/dev/sdX bs=4M status=progress
-
- # Or use Raspberry Pi Imager
- ```
-
-4. **Boot** the Raspberry Pi:
-
- - Insert microSD card
- - Connect power and network
- - Wait 10-20 minutes for first-boot setup
- - SSH into `minecraft-server.local` or check IP
-
-5. **Verify** setup:
- ```bash
- ssh pi@minecraft-server.local
- cd ~/minecraft-server
- ./manage.sh status
- ```
-
-## Pipeline Triggers
-
-### Automatic Triggers
-
-- **Push to main/develop**: Runs all tests and builds
-- **Pull Request**: Runs all tests (no image build)
-- **Push to main**: Builds Raspberry Pi image
-
-### Manual Triggers
-
-Use GitHub Actions UI to manually trigger:
-
-- Run all tests
-- Build image (set `build_image: true`)
-
-## Critical vs Non-Critical Jobs
-
-### Critical (Must Pass)
-
-- ✅ Lint
-- ✅ Python Tests
-- ✅ Bash Tests
-- ✅ Docker Build
-
-### Non-Critical (Can Fail)
-
-- ⚠️ Frontend Tests
-- ⚠️ Playwright Tests
-
-## Artifacts
-
-### Playwright Report
-
-- **Location**: `web/playwright-report/`
-- **Retention**: 30 days
-- **Access**: Download from workflow run
-
-### Raspberry Pi Image
-
-- **Location**: Root directory
-- **Format**: `.img.xz` (compressed)
-- **Retention**: 90 days
-- **Access**:
- - Artifacts (main branch)
- - GitHub Releases (tags)
-
-## Troubleshooting
-
-### Playwright Tests Failing
-
-Since Playwright tests are non-blocking, failures won't block the pipeline. To investigate:
-
-1. Download the Playwright report artifact
-2. Open `index.html` in a browser
-3. Review test failures and screenshots
-4. Check test logs for errors
-
-### Image Build Failing
-
-Common issues:
-
-1. **Download timeout**: Raspberry Pi OS download may timeout
-
- - **Solution**: Workflow will retry, or manually trigger
-
-2. **Disk space**: Image building requires ~10GB free space
-
- - **Solution**: GitHub Actions runners have sufficient space
-
-3. **QEMU issues**: ARM emulation may fail
- - **Solution**: Check QEMU setup step logs
-
-### Pipeline Summary
-
-The summary job provides an overview of all job results. Check the workflow run summary for:
-
-- Job status (✅ success, ❌ failure, ⚠️ skipped)
-- Critical job failures
-- Non-critical job warnings
-
-## Migration from Separate Workflows
-
-The old separate workflows are still present but can be disabled:
-
-- `ci.yml` → Merged into `main.yml` (lint job)
-- `tests.yml` → Merged into `main.yml` (python-tests, bash-tests)
-- `playwright.yml` → Merged into `main.yml` (playwright-tests, non-blocking)
-- `coverage.yml` → Can be kept separate or merged
-- `release.yml` → Image building replaces Docker image push
-
-To disable old workflows, add this to each:
-
-```yaml
-on:
- workflow_dispatch: # Only manual trigger
-```
-
-## Optimizations
-
-The pipeline has been optimized for speed and efficiency. See [CI/CD Optimizations](CI_CD_OPTIMIZATIONS.md) for detailed information about:
-
-- Dependency caching (Python, Node.js, BATS, APT, RPi OS image)
-- Docker build optimizations
-- Image build optimizations
-- Job parallelization
-- Resource management
-
-**Key Benefits:**
-- 1-2 minutes saved on typical runs
-- 7-20 minutes saved on image builds (with cache hits)
-- Reduced resource usage
-- Faster feedback cycles
-
-## Future Enhancements
-
-Potential improvements:
-
-1. **Matrix builds**: Test on multiple Python/Node versions
-2. **Docker registry push**: Push images to GHCR
-3. **Image signing**: Sign images for security
-4. **Automated testing**: Test the built image in QEMU
-5. **Multi-architecture**: Support Raspberry Pi 4 (ARM32)
-6. **Larger runners**: Use 4-core runners for image builds
-7. **Parallel operations**: Further parallelize image customization
diff --git a/docs/archive/CONSOLIDATION_NOTES.md b/docs/archive/CONSOLIDATION_NOTES.md
deleted file mode 100644
index af871b6..0000000
--- a/docs/archive/CONSOLIDATION_NOTES.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Documentation Consolidation Notes
-
-This document explains the documentation reorganization that took place to improve organization and reduce redundancy.
-
-## Changes Made
-
-### 1. Created Documentation Index
-
-- **New**: `docs/INDEX.md` - Central navigation hub for all documentation
-- Provides organized access to all docs by category
-- Includes quick navigation and topic-based organization
-
-### 2. Consolidated Implementation Summaries
-
-- **Archived**: Multiple implementation summary files moved to `docs/archive/`
-- **Reason**: These were historical snapshots that duplicated information in CHANGELOG.md
-- **Action**: Future implementation notes should go directly in CHANGELOG.md
-
-### 3. Reorganized README References
-
-- **Updated**: Main README.md documentation section
-- **Improvement**: Clearer categorization (Getting Started, User Guides, Developer Guides)
-- **Added**: Link to documentation index for easy navigation
-
-### 4. Created Documentation README
-
-- **New**: `docs/README.md` - Explains documentation structure
-- **Purpose**: Helps contributors understand where to add new docs
-
-### 5. Archive Directory
-
-- **Created**: `docs/archive/` for superseded documentation
-- **Purpose**: Preserve historical documents without cluttering main docs
-- **Note**: Archived files are still accessible but marked as historical
-
-## Documentation Structure
-
-### Before
-
-- Multiple implementation summary files in root
-- Duplicate files in root and docs/
-- No clear navigation structure
-- Hard to find specific documentation
-
-### After
-
-- Single documentation index (`docs/INDEX.md`)
-- Clear categorization (User/Developer/Reference)
-- Archived historical documents
-- Easy navigation from README
-
-## File Locations
-
-### Current Documentation
-
-- **Main Index**: `docs/INDEX.md`
-- **Installation**: `docs/INSTALL.md`
-- **Quick Reference**: `docs/QUICK_REFERENCE.md`
-- **User Guides**: `docs/*.md` (feature-specific)
-- **Developer Guides**: `docs/DEVELOPMENT.md`, `docs/TESTING.md`, etc.
-
-### Archived Files
-
-- `docs/archive/IMPLEMENTATION_SUMMARY.md`
-- `docs/archive/IMPLEMENTATION_SUMMARY_P1.md`
-- `docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md`
-- `docs/archive/IMPLEMENTATION_SUMMARY_docs.md`
-
-## Best Practices Going Forward
-
-### Adding New Documentation
-
-1. **Choose the right location**:
-
- - User guides → `docs/` (feature name)
- - Developer guides → `docs/DEVELOPMENT.md` or new file
- - Reference → `docs/QUICK_REFERENCE.md` or `docs/CONFIGURATION_EXAMPLES.md`
-
-2. **Update the index**:
-
- - Add entry to `docs/INDEX.md`
- - Update appropriate category section
- - Add cross-references if needed
-
-3. **Update README**:
- - Add link in main README.md if user-facing
- - Keep documentation section organized
-
-### Version History
-
-- **Use CHANGELOG.md** for implementation summaries
-- **Avoid** creating separate implementation summary files
-- **Document** features as they're implemented in CHANGELOG
-
-### Consolidation
-
-- **Review periodically** for duplicate content
-- **Archive** superseded documentation
-- **Keep** documentation index up to date
-
-## Benefits
-
-1. **Easier Navigation**: Single index makes finding docs simple
-2. **Reduced Redundancy**: No duplicate implementation summaries
-3. **Better Organization**: Clear categories for different audiences
-4. **Historical Preservation**: Archived files still accessible
-5. **Maintainability**: Clear structure makes updates easier
-
-## Migration Notes
-
-If you have bookmarks or links to old documentation:
-
-- Implementation summaries → See `CHANGELOG.md` for version history
-- All other docs → Same location, just better organized
-- Use `docs/INDEX.md` to find any documentation
-
----
-
-**Consolidation Date**: 2025-01-XX
-**Next Review**: As needed when documentation grows
diff --git a/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md b/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md
deleted file mode 100644
index 07fe466..0000000
--- a/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md
+++ /dev/null
@@ -1,356 +0,0 @@
-# Complete Implementation Summary
-
-This document summarizes ALL critical (P0) and high-priority (P1) features that have been implemented.
-
-## Implementation Statistics
-
-- **P0 Tasks Completed**: 14 tasks
-- **P1 Tasks Completed**: 12 tasks
-- **Total Features Implemented**: 26 tasks
-- **New Scripts Created**: 15 scripts
-- **New Documentation**: 4 comprehensive guides
-
----
-
-## Phase 1: Core Enhancements (v1.1.0)
-
-### ✅ Backup & Scheduling (6 P0 tasks)
-
-1. **Cron-based Backup Scheduling** (`scripts/backup-scheduler.sh`)
- - Configurable daily/weekly/monthly schedules
- - Time-of-day configuration
- - Logging system
-
-2. **Systemd Timer Support** (`systemd/minecraft-backup.service`, `systemd/minecraft-backup.timer`)
- - Reliable systemd-based scheduling
- - Persistent timers
- - Easy installation script
-
-3. **Backup Retention Policy** (`scripts/cleanup-backups.sh`)
- - Keep last N backups
- - Separate retention for daily/weekly/monthly
- - Automatic cleanup
-
-4. **Pre-backup World Save** (Enhanced `scripts/manage.sh`)
- - Automatic `save-all` before backup
- - Works with/without RCON
-
-5. **Backup Verification** (Enhanced `scripts/manage.sh`)
- - Integrity checks
- - File count verification
- - Size reporting
-
-6. **Backup Compression** (Enhanced `scripts/manage.sh`)
- - Optimized gzip compression
- - Size reporting
-
-### ✅ Monitoring & Metrics (8 P0 tasks)
-
-1. **TPS Monitoring** (`scripts/monitor.sh`)
- - Extracts TPS from logs
- - CSV storage format
-
-2. **Memory Usage Monitoring** (`scripts/monitor.sh`)
- - Docker stats integration
- - Memory leak detection capability
-
-3. **CPU Usage Tracking** (`scripts/monitor.sh`)
- - CPU percentage monitoring
- - Historical tracking
-
-4. **Player Count Analytics** (`scripts/monitor.sh`)
- - Player count over time
- - Peak hours analysis capability
-
-5. **Server Uptime Tracking** (`scripts/monitor.sh`)
- - Calculates uptime from container start
- - Historical tracking
-
-6. **Log Aggregation** (docker-compose.yml)
- - Docker log rotation
- - 10MB per file, 3 files max
-
-7. **Health Check Endpoints** (`scripts/health-check.sh`)
- - Container status
- - Java process verification
- - Port listening checks
- - CPU/memory thresholds
-
-8. **Prometheus Metrics Export** (`scripts/prometheus-exporter.sh`)
- - Prometheus format
- - HTTP endpoint support
- - All key metrics exposed
-
----
-
-## Phase 1: Update Management (v1.1.0)
-
-### ✅ Update Management (3 P1 tasks)
-
-1. **Automatic Version Checking** (`scripts/check-version.sh`)
- - Queries Mojang API
- - Compares versions
- - Configurable frequency
-
-2. **One-Command Server Updates** (Enhanced `scripts/manage.sh`)
- - Automatic backup
- - Downloads new jar
- - Updates configuration
- - Rebuilds container
-
-3. **Version Compatibility Checking** (`scripts/check-compatibility.sh`)
- - World compatibility
- - Plugin compatibility
- - Mod compatibility
- - Configuration validation
-
----
-
-## Phase 1: Server Variants (v1.2.0)
-
-### ✅ Server Implementation Support (5 P1 tasks)
-
-1. **Server Type Selection** (`scripts/switch-server-type.sh`)
- - Switch between Vanilla, Paper, Spigot, Fabric
- - Automatic configuration updates
-
-2. **Automatic Server Jar Download** (`scripts/download-server.sh`)
- - Universal downloader
- - Supports Vanilla, Paper, Fabric
- - Version-specific URLs
-
-3. **Paper Server Support** (Integrated in download-server.sh)
- - PaperMC API integration
- - Automatic build selection
-
-4. **Fabric Server Support** (Integrated in download-server.sh)
- - Fabric installer integration
- - Automatic server generation
-
-5. **Spigot Server Support** (Documented)
- - BuildTools reference
- - Manual build process
-
----
-
-## Phase 1: Plugin Management (v1.2.0)
-
-### ✅ Plugin Management (4 P1 tasks)
-
-1. **Plugin Installation System** (`scripts/plugin-manager.sh`)
- - Install from .jar files
- - Plugin info extraction
- - Automatic backups
-
-2. **Plugin Update Mechanism** (`scripts/plugin-manager.sh`)
- - Update with new .jar
- - Configuration backup
- - Version comparison
-
-3. **Plugin Enable/Disable** (`scripts/plugin-manager.sh`)
- - Enable/disable without removal
- - Disabled plugins directory
- - State tracking
-
-4. **Plugin Configuration Management** (`scripts/plugin-config-manager.sh`)
- - Configuration validation
- - Backup/restore
- - Template system
-
----
-
-## Files Created
-
-### Scripts (15 files)
-1. `scripts/backup-scheduler.sh` - Backup scheduling
-2. `scripts/cleanup-backups.sh` - Backup retention
-3. `scripts/install-backup-timer.sh` - Systemd timer installer
-4. `scripts/monitor.sh` - Metrics collection
-5. `scripts/health-check.sh` - Health checks
-6. `scripts/prometheus-exporter.sh` - Prometheus export
-7. `scripts/check-version.sh` - Version checking
-8. `scripts/download-server.sh` - Server downloader
-9. `scripts/switch-server-type.sh` - Server type switcher
-10. `scripts/check-compatibility.sh` - Compatibility checking
-11. `scripts/plugin-manager.sh` - Plugin management
-12. `scripts/plugin-config-manager.sh` - Plugin config management
-
-### Configuration Files (3 files)
-1. `config/backup-schedule.conf` - Backup scheduling config
-2. `config/backup-retention.conf` - Backup retention config
-3. `config/update-check.conf` - Update check config
-
-### Systemd Files (2 files)
-1. `systemd/minecraft-backup.service` - Backup service
-2. `systemd/minecraft-backup.timer` - Backup timer
-
-### Documentation (4 files)
-1. `docs/BACKUP_AND_MONITORING.md` - Backup & monitoring guide
-2. `docs/UPDATE_MANAGEMENT.md` - Update management guide
-3. `docs/PLUGIN_MANAGEMENT.md` - Plugin management guide
-4. `IMPLEMENTATION_SUMMARY.md` - P0 features summary
-5. `IMPLEMENTATION_SUMMARY_P1.md` - P1 features summary
-6. `FINAL_IMPLEMENTATION_SUMMARY.md` - This file
-
----
-
-## Enhanced Files
-
-1. `scripts/manage.sh` - Added:
- - Enhanced backup with save & verification
- - Update server command
- - Check version command
- - Check compatibility command
- - Plugin management integration
-
-2. `scripts/start.sh` - Enhanced to:
- - Support SERVER_TYPE variable
- - Auto-detect jar filename by server type
-
-3. `docker-compose.yml` - Enhanced:
- - Improved healthcheck
- - Plugin volume mount
-
-4. `README.md` - Updated:
- - New features list
- - New commands
- - Documentation links
-
----
-
-## Quick Reference
-
-### Backup Management
-```bash
-./scripts/manage.sh backup # Manual backup
-./scripts/backup-scheduler.sh # Run scheduled backup
-./scripts/cleanup-backups.sh # Clean old backups
-./scripts/install-backup-timer.sh # Install systemd timer
-```
-
-### Monitoring
-```bash
-./scripts/monitor.sh # Collect metrics
-./scripts/health-check.sh # Check server health
-./scripts/prometheus-exporter.sh # Export Prometheus metrics
-```
-
-### Updates
-```bash
-./scripts/manage.sh check-version # Check for updates
-./scripts/manage.sh update [version] # Update server
-./scripts/manage.sh check-compatibility # Check compatibility
-```
-
-### Server Types
-```bash
-./scripts/switch-server-type.sh list # List types
-./scripts/switch-server-type.sh paper # Switch to Paper
-./scripts/download-server.sh --type paper --version 1.21.0
-```
-
-### Plugins
-```bash
-./scripts/manage.sh plugins list # List plugins
-./scripts/manage.sh plugins install # Install plugin
-./scripts/manage.sh plugins enable # Enable plugin
-./scripts/manage.sh plugins disable # Disable plugin
-./scripts/manage.sh plugins update # Update plugin
-./scripts/plugin-config-manager.sh list # List configs
-./scripts/plugin-config-manager.sh validate # Validate config
-```
-
----
-
-## Key Features Summary
-
-### Automation
-- ✅ Automated backup scheduling (cron/systemd)
-- ✅ Automatic backup retention cleanup
-- ✅ Automatic version checking
-- ✅ One-command server updates
-
-### Monitoring
-- ✅ Real-time metrics collection
-- ✅ Health check endpoints
-- ✅ Prometheus metrics export
-- ✅ Performance tracking (TPS, CPU, Memory)
-
-### Management
-- ✅ Multiple server types (Vanilla, Paper, Spigot, Fabric)
-- ✅ Plugin installation & management
-- ✅ Configuration management
-- ✅ Update management with compatibility checks
-
-### Reliability
-- ✅ Backup verification
-- ✅ Pre-backup world saves
-- ✅ Configuration backups
-- ✅ Rollback capabilities
-
----
-
-## Testing Status
-
-All scripts have been created with:
-- Error handling
-- Input validation
-- User-friendly output
-- Comprehensive logging
-- Documentation
-
-**Recommended Testing:**
-1. Test backup scheduling on Raspberry Pi
-2. Test server type switching
-3. Test plugin installation
-4. Test update process
-5. Verify monitoring metrics collection
-
----
-
-## Next Steps
-
-### Remaining P1 Tasks
-- None! All P1 tasks are complete.
-
-### P2 Tasks (Medium Priority)
-- Multi-world support
-- Advanced server management (RCON, API)
-- Dynamic DNS integration
-- Cloud backup integration
-
-### Future Enhancements
-- Web admin panel (v1.4.0)
-- Mobile app (v1.6.0)
-- Multi-server orchestration (v2.0.0)
-
----
-
-## Documentation
-
-All features are documented in:
-- `docs/BACKUP_AND_MONITORING.md`
-- `docs/UPDATE_MANAGEMENT.md`
-- `docs/PLUGIN_MANAGEMENT.md`
-- `README.md` (updated with all new features)
-
----
-
-## Conclusion
-
-**26 critical and high-priority features have been successfully implemented**, providing:
-
-1. **Complete backup automation** with scheduling and retention
-2. **Comprehensive monitoring** with metrics and health checks
-3. **Easy update management** with compatibility checking
-4. **Multiple server type support** with automatic downloads
-5. **Full plugin management** with configuration handling
-
-The Minecraft server setup is now production-ready with enterprise-grade features for automation, monitoring, and management.
-
----
-
-**Implementation Date**: 2025-01-XX
-**Total Development Time**: Comprehensive feature set
-**Status**: ✅ All P0 and P1 tasks complete
-
diff --git a/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md b/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md
deleted file mode 100644
index 2c0ba97..0000000
--- a/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# Gameplay Features Implementation Summary
-
-This document summarizes the three high-priority gameplay features that have been implemented.
-
-## ✅ Completed Features
-
-### 1. Enhanced Command Scheduler ✅
-
-**Status**: Complete
-**File**: `scripts/command-scheduler.py`
-**API Endpoints**: `/api/commands/schedules`, `/api/commands/schedule`, etc.
-
-#### Features Added:
-
-- **Cron Expression Support**: Full cron syntax for flexible scheduling
-- **Conditional Execution**: Run commands based on:
- - Player count thresholds (e.g., only if > 5 players)
- - Time ranges (peak hours)
- - Day of week filters
-- **Multiple Schedule Types**:
- - `interval` - Run every X minutes/hours
- - `daily` - Run at specific time daily
- - `weekly` - Run on specific day at specific time
- - `cron` - Full cron expression support
- - `once` - Run once at specific datetime
-- **Command Templates**: Variables like `{time}`, `{date}`, `{player_count}`, `{datetime}`
-- **Schedule Management**: Enable/disable, list, create, delete schedules
-
-#### Usage Examples:
-
-```bash
-# Create a daily announcement at 6 PM
-./scripts/command-scheduler.py add "say Peak hours!" daily --run_time "18:00"
-
-# Create conditional command (only if > 5 players)
-# Via API: POST /api/commands/schedule with condition
-
-# Create cron schedule (every hour at minute 0)
-./scripts/command-scheduler.py add "say Hourly reminder" cron --cron_expression "0 * * * *"
-```
-
-#### API Endpoints:
-
-- `GET /api/commands/schedules` - List all schedules
-- `POST /api/commands/schedule` - Create new schedule
-- `DELETE /api/commands/schedule/` - Delete schedule
-- `PUT /api/commands/schedule//enable` - Enable schedule
-- `PUT /api/commands/schedule//disable` - Disable schedule
-
----
-
-### 2. Player Statistics Tracker ✅
-
-**Status**: Complete
-**File**: `scripts/player-stats-tracker.sh`
-**API Endpoints**: `/api/players/stats`, `/api/players/stats/`, etc.
-
-#### Features Added:
-
-- **Player Tracking**: Automatic tracking from server logs
-- **Statistics Collected**:
- - Login/logout counts
- - Play time (session tracking)
- - Death count
- - Blocks broken/placed
- - First seen / Last seen timestamps
-- **Leaderboards**: Top players by any metric
-- **Log Parsing**: Automatic parsing of server logs for player events
-- **JSON Storage**: All stats stored in JSON format
-
-#### Usage Examples:
-
-```bash
-# Parse server logs for player events
-./scripts/player-stats-tracker.sh parse
-
-# Get player statistics
-./scripts/player-stats-tracker.sh get PlayerName
-
-# Get leaderboard (top 10 by login count)
-./scripts/player-stats-tracker.sh leaderboard login_count 10
-
-# Update player stat manually
-./scripts/player-stats-tracker.sh update PlayerName blocks_broken 100
-```
-
-#### API Endpoints:
-
-- `GET /api/players/stats` - Get all player statistics
-- `GET /api/players/stats/` - Get specific player stats
-- `GET /api/players/stats/leaderboard?metric=&limit=` - Get leaderboard
-- `POST /api/players/stats/parse` - Parse server logs for stats
-
-#### Statistics Tracked:
-
-- `login_count` - Number of times player logged in
-- `logout_count` - Number of times player logged out
-- `deaths` - Number of deaths
-- `blocks_broken` - Blocks broken
-- `blocks_placed` - Blocks placed
-- `first_seen` - First seen timestamp
-- `last_seen` - Last seen timestamp
-
----
-
-### 3. Announcement System ✅
-
-**Status**: Complete
-**File**: `scripts/announcement-manager.sh`
-**API Endpoints**: `/api/announcements`, etc.
-
-#### Features Added:
-
-- **Multiple Announcement Types**:
- - `say` - Chat message
- - `title` - Title text
- - `subtitle` - Subtitle text
- - `actionbar` - Actionbar message
-- **Scheduled Announcements**: Support for daily/weekly schedules
-- **Storage**: JSON-based storage for announcements
-- **Immediate Send**: Send announcements immediately via API
-- **Management**: Create, list, send, delete announcements
-
-#### Usage Examples:
-
-```bash
-# Create simple announcement
-./scripts/announcement-manager.sh create "Welcome to our server!" say
-
-# Create scheduled title announcement
-./scripts/announcement-manager.sh create \
- "Server restart in 10 minutes" \
- title \
- daily \
- "02:50"
-
-# Send announcement immediately
-./scripts/announcement-manager.sh send
-
-# List all announcements
-./scripts/announcement-manager.sh list
-
-# Delete announcement
-./scripts/announcement-manager.sh delete
-```
-
-#### API Endpoints:
-
-- `GET /api/announcements` - List all announcements
-- `POST /api/announcements` - Create new announcement
-- `POST /api/announcements//send` - Send announcement immediately
-- `DELETE /api/announcements/` - Delete announcement
-
-#### Request Body Example:
-
-```json
-{
- "message": "Welcome to our server!",
- "type": "title",
- "schedule_type": "daily",
- "schedule_time": "12:00",
- "enabled": true
-}
-```
-
----
-
-## Integration Points
-
-All features integrate with:
-
-1. **RCON**: Commands executed via RCON client
-2. **REST API**: Full API access for web interface
-3. **Web UI**: Ready for React component integration
-4. **Logging**: Comprehensive logging and audit trails
-5. **Permissions**: RBAC permission system
-
-## Configuration Files
-
-- **Command Schedules**: `config/command-schedule.json`
-- **Player Stats**: `data/stats/player-stats.json`
-- **Announcements**: `config/announcements.json`
-
-## Dependencies
-
-### Required:
-
-- Python 3.x
-- Bash 4.x+
-- RCON client (via rcon-client.sh)
-
-### Optional:
-
-- `croniter` (for cron expression support) - Added to `api/requirements.txt`
-
-## Next Steps
-
-These features are now ready for:
-
-1. **Web UI Integration**: Create React components for:
-
- - Command scheduler management UI
- - Player statistics dashboard
- - Announcement management interface
-
-2. **Testing**: Create test cases for:
-
- - Command scheduler execution
- - Player stats tracking
- - Announcement delivery
-
-3. **Documentation**: Add to main documentation:
- - User guide for command scheduling
- - Player statistics guide
- - Announcement system guide
-
-## See Also
-
-- [Minecraft Gameplay Enhancements](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) - Full enhancement roadmap
-- [API Documentation](API.md) - Complete API reference
-- [Web Interface Guide](WEB_INTERFACE.md) - Web UI integration
diff --git a/docs/archive/IMPLEMENTATION_SUMMARY.md b/docs/archive/IMPLEMENTATION_SUMMARY.md
deleted file mode 100644
index 1f712e9..0000000
--- a/docs/archive/IMPLEMENTATION_SUMMARY.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Critical Features Implementation Summary
-
-This document summarizes the critical P0 features that have been implemented.
-
-## Completed Features (P0 - Critical)
-
-### Backup & Scheduling ✅
-
-#### 1. Cron-based Backup Scheduling (Task 1.1.1)
-
-- **File**: `scripts/backup-scheduler.sh`
-- **Config**: `config/backup-schedule.conf`
-- **Features**:
- - Supports daily, weekly, and monthly schedules
- - Configurable time-of-day execution
- - Logging to `logs/backup-scheduler.log`
- - Automatic cleanup integration
-
-#### 2. Systemd Timer for Backups (Task 1.1.2)
-
-- **Files**:
- - `systemd/minecraft-backup.service`
- - `systemd/minecraft-backup.timer`
- - `scripts/install-backup-timer.sh`
-- **Features**:
- - Systemd-based scheduling (more reliable than cron)
- - Runs daily at 3:00 AM by default
- - Persistent timers (runs missed backups on boot)
- - Easy installation script
-
-#### 3. Backup Retention Policy (Task 1.1.3)
-
-- **File**: `scripts/cleanup-backups.sh`
-- **Config**: `config/backup-retention.conf`
-- **Features**:
- - Keep last N backups regardless of age
- - Separate retention for daily/weekly/monthly backups
- - Automatic classification of backup types
- - Size reporting after cleanup
-
-#### 4. Pre-backup World Save (Task 1.1.4)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Automatically executes `save-all` before backup
- - Works with or without RCON
- - Waits for save completion
- - Error handling
-
-#### 5. Backup Verification (Task 1.1.5)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Verifies backup integrity using tar test
- - Counts files in backup
- - Reports backup size
- - Fails if verification fails
-
-#### 6. Backup Compression (Task 1.1.6)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Uses gzip compression (tar.gz)
- - Reports compressed size
- - Can be extended for other compression algorithms
-
-### Monitoring & Metrics ✅
-
-#### 7. TPS Monitoring (Task 1.2.1)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Extracts TPS from server logs
- - Stores TPS history in CSV format
- - Logs to `metrics/tps.csv`
-
-#### 8. Memory Usage Monitoring (Task 1.2.2)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Tracks memory usage via Docker stats
- - Records memory consumption over time
- - Logs to `metrics/memory_usage.csv`
- - Can detect memory leaks (via trend analysis)
-
-#### 9. CPU Usage Tracking (Task 1.2.3)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Monitors CPU usage percentage
- - Tracks CPU over time
- - Logs to `metrics/cpu_usage.csv`
- - Can be extended for per-core tracking
-
-#### 10. Player Count Analytics (Task 1.2.4)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Tracks player count over time
- - Extracts from server logs
- - Logs to `metrics/player_count.csv`
- - Can be used for peak hours analysis
-
-#### 11. Server Uptime Tracking (Task 1.2.5)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Calculates uptime from container start time
- - Tracks uptime in seconds
- - Logs to `metrics/server_uptime.csv`
-
-#### 12. Log Aggregation (Task 1.2.6)
-
-- **Features**:
- - Docker logging with rotation (configured in docker-compose.yml)
- - Logs stored in Docker's JSON log driver
- - Max size: 10MB per file
- - Max files: 3 (30MB total)
-
-#### 13. Health Check Endpoints (Task 1.2.7)
-
-- **File**: `scripts/health-check.sh`
-- **Features**:
- - Checks container status
- - Verifies Java process
- - Checks port listening
- - Monitors CPU and memory thresholds
- - Returns exit codes for automation
- - Integrated into docker-compose.yml healthcheck
-
-#### 14. Prometheus Metrics Export (Task 1.2.8)
-
-- **File**: `scripts/prometheus-exporter.sh`
-- **Features**:
- - Exports metrics in Prometheus format
- - HTTP endpoint support (port 9091)
- - All key metrics exposed
- - Ready for Grafana integration
-
-## New Files Created
-
-### Scripts
-
-1. `scripts/backup-scheduler.sh` - Cron/systemd backup scheduler
-2. `scripts/cleanup-backups.sh` - Backup retention cleanup
-3. `scripts/install-backup-timer.sh` - Systemd timer installer
-4. `scripts/monitor.sh` - Metrics collection script
-5. `scripts/health-check.sh` - Health check script
-6. `scripts/prometheus-exporter.sh` - Prometheus metrics exporter
-
-### Configuration Files
-
-1. `config/backup-schedule.conf` - Backup scheduling configuration
-2. `config/backup-retention.conf` - Backup retention policy
-
-### Systemd Files
-
-1. `systemd/minecraft-backup.service` - Systemd service file
-2. `systemd/minecraft-backup.timer` - Systemd timer file
-
-### Documentation
-
-1. `docs/BACKUP_AND_MONITORING.md` - Comprehensive backup & monitoring guide
-
-## Enhanced Files
-
-1. `scripts/manage.sh` - Enhanced backup function with:
- - Pre-backup world save
- - Backup verification
- - Better error handling
- - Improved RCON command sending
-
-2. `docker-compose.yml` - Enhanced healthcheck configuration
-
-3. `docs/QUICK_REFERENCE.md` - Added new commands
-
-4. `README.md` - Updated features list and backup section
-
-## Usage Examples
-
-### Setup Automated Backups
-
-```bash
-# Install systemd timer
-./scripts/install-backup-timer.sh
-
-# Or configure cron
-crontab -e
-# Add: 0 3 * * * /path/to/minecraft-server/scripts/backup-scheduler.sh
-```
-
-### Run Monitoring
-
-```bash
-# Collect metrics once
-./scripts/monitor.sh
-
-# Set up periodic monitoring (every 5 minutes)
-*/5 * * * * /path/to/minecraft-server/scripts/monitor.sh
-```
-
-### Check Server Health
-
-```bash
-# Run health check
-./scripts/health-check.sh
-
-# Use in monitoring
-if ./scripts/health-check.sh; then
- echo "Server healthy"
-fi
-```
-
-### Export Prometheus Metrics
-
-```bash
-# Output metrics
-./scripts/prometheus-exporter.sh
-
-# Serve on HTTP (requires netcat or HTTP server)
-./scripts/prometheus-exporter.sh --serve
-```
-
-## Next Steps
-
-The following P0 tasks are now complete. Remaining P0 tasks from TASKS.md:
-
-- ✅ All Backup & Scheduling tasks (1.1.1 - 1.1.6)
-- ✅ All Monitoring & Metrics tasks (1.2.1 - 1.2.8)
-
-**Next Priority Tasks (P1):**
-
-- Update Management (Tasks 1.3.1 - 1.3.3)
-- Server Variants & Plugins (Tasks 2.1.1 - 2.2.4)
-
-## Testing Recommendations
-
-1. **Backup Testing**:
- - Test manual backup: `./scripts/manage.sh backup`
- - Test scheduler: `./scripts/backup-scheduler.sh`
- - Test cleanup: `./scripts/cleanup-backups.sh`
- - Verify backups can be restored
-
-2. **Monitoring Testing**:
- - Run monitor script: `./scripts/monitor.sh`
- - Check metrics files in `metrics/` directory
- - Test health check: `./scripts/health-check.sh`
- - Test Prometheus exporter: `./scripts/prometheus-exporter.sh`
-
-3. **Systemd Timer Testing**:
- - Install timer: `./scripts/install-backup-timer.sh`
- - Check status: `sudo systemctl status minecraft-backup.timer`
- - Test run: `sudo systemctl start minecraft-backup.service`
- - Check logs: `sudo journalctl -u minecraft-backup.service`
-
-## Notes
-
-- All scripts are designed to work on Linux/Raspberry Pi OS
-- Scripts use bash and require standard Unix utilities
-- Configuration files use simple shell variable syntax
-- Metrics are stored in CSV format for easy analysis
-- Health checks return proper exit codes for automation
diff --git a/docs/archive/IMPLEMENTATION_SUMMARY_P1.md b/docs/archive/IMPLEMENTATION_SUMMARY_P1.md
deleted file mode 100644
index 6b12e7d..0000000
--- a/docs/archive/IMPLEMENTATION_SUMMARY_P1.md
+++ /dev/null
@@ -1,275 +0,0 @@
-# P1 Features Implementation Summary
-
-This document summarizes the P1 (High Priority) features that have been implemented.
-
-## Completed Features (P1 - High Priority)
-
-### Update Management ✅
-
-#### 1. Automatic Version Checking (Task 1.3.1)
-
-- **File**: `scripts/check-version.sh`
-- **Config**: `config/update-check.conf`
-- **Features**:
- - Queries Mojang version manifest API
- - Compares current vs latest version
- - Configurable check frequency
- - Notification system
- - Integrated into `manage.sh check-version`
-
-#### 2. One-Command Server Updates (Task 1.3.2)
-
-- **File**: `scripts/manage.sh` (enhanced `update_server()`)
-- **Features**:
- - Automatic backup before update
- - Downloads new server jar
- - Updates docker-compose.yml
- - Rebuilds container
- - Restarts server
- - Rollback capability via backups
- - Usage: `./manage.sh update [version]`
-
-#### 3. Version Compatibility Checking (Task 1.3.3)
-
-- **File**: `scripts/check-compatibility.sh`
-- **Features**:
- - Checks world compatibility
- - Verifies plugin compatibility
- - Checks mod compatibility
- - Validates configuration files
- - Detects major vs minor version changes
- - Integrated into update process
- - Usage: `./manage.sh check-compatibility `
-
-### Server Variants & Download ✅
-
-#### 4. Server Type Selection System (Task 2.1.4)
-
-- **File**: `scripts/switch-server-type.sh`
-- **Features**:
- - Switch between Vanilla, Paper, Spigot, Fabric
- - Lists available types
- - Shows current type
- - Updates docker-compose.yml automatically
- - Downloads server jar if needed
- - Usage: `./switch-server-type.sh `
-
-#### 5. Automatic Server Jar Download (Task 2.1.5)
-
-- **File**: `scripts/download-server.sh`
-- **Features**:
- - Supports Vanilla, Paper, Fabric
- - Version-specific URLs
- - Download verification
- - Automatic file naming
- - Error handling
- - Usage: `./download-server.sh --type --version `
-
-#### 6. Paper Server Support (Task 2.1.1)
-
-- **Implementation**: Integrated into download-server.sh
-- **Features**:
- - Queries PaperMC API
- - Downloads latest Paper build for version
- - Automatic jar naming
- - Ready for use with SERVER_TYPE=paper
-
-#### 7. Fabric Server Support (Task 2.1.3)
-
-- **Implementation**: Integrated into download-server.sh
-- **Features**:
- - Downloads Fabric installer
- - Runs installer automatically
- - Generates Fabric server jar
- - Ready for use with SERVER_TYPE=fabric
-
-#### 8. Spigot Server Support (Task 2.1.2)
-
-- **Status**: Partial (requires BuildTools)
-- **Implementation**: Noted in download-server.sh
-- **Note**: Spigot requires BuildTools to build from source
-- **Documentation**: References provided
-
-## New Files Created
-
-### Scripts
-
-1. `scripts/check-version.sh` - Version checking script
-2. `scripts/download-server.sh` - Universal server downloader
-3. `scripts/switch-server-type.sh` - Server type switcher
-4. `scripts/check-compatibility.sh` - Compatibility checker
-
-### Configuration Files
-
-1. `config/update-check.conf` - Update check configuration
-
-### Documentation
-
-1. `docs/UPDATE_MANAGEMENT.md` - Comprehensive update management guide
-
-## Enhanced Files
-
-1. `scripts/manage.sh` - Added:
- - `update_server()` function
- - `check-version` command
- - `check-compatibility` command
- - Integration with compatibility checking
-
-2. `scripts/start.sh` - Enhanced to:
- - Support SERVER_TYPE environment variable
- - Auto-detect jar filename based on server type
- - Support Paper, Fabric, Spigot jar naming
-
-3. `README.md` - Updated with:
- - New commands
- - Server type information
- - Update management features
-
-## Usage Examples
-
-### Check for Updates
-
-```bash
-# Check if updates are available
-./scripts/manage.sh check-version
-
-# Or use script directly
-./scripts/check-version.sh
-```
-
-### Update Server
-
-```bash
-# Update to latest version
-./scripts/manage.sh update
-
-# Update to specific version
-./scripts/manage.sh update 1.21.0
-
-# Check compatibility first
-./scripts/manage.sh check-compatibility 1.21.0
-```
-
-### Switch Server Type
-
-```bash
-# List available types
-./scripts/switch-server-type.sh list
-
-# Check current type
-./scripts/switch-server-type.sh current
-
-# Switch to Paper
-./scripts/switch-server-type.sh paper
-
-# Switch to Fabric
-./scripts/switch-server-type.sh fabric
-
-# Switch back to Vanilla
-./scripts/switch-server-type.sh vanilla
-```
-
-### Download Server Jars
-
-```bash
-# Download Vanilla
-./scripts/download-server.sh --type vanilla --version 1.21.0
-
-# Download Paper
-./scripts/download-server.sh --type paper --version 1.21.0
-
-# Download Fabric
-./scripts/download-server.sh --type fabric --version 1.21.0
-```
-
-## Integration Points
-
-### Docker Compose
-
-Server type is configured via environment variable:
-
-```yaml
-environment:
- - SERVER_TYPE=paper # vanilla, paper, spigot, or fabric
-```
-
-### Start Script
-
-The start script automatically detects the server type and uses the appropriate jar file.
-
-### Update Process
-
-The update process:
-
-1. Checks compatibility
-2. Creates backup
-3. Downloads new jar
-4. Updates configuration
-5. Rebuilds container
-6. Restarts server
-
-## API Integrations
-
-### Mojang Version Manifest API
-
-- **URL**: `https://launchermeta.mojang.com/mc/game/version_manifest.json`
-- **Used for**: Getting latest versions and download URLs
-
-### PaperMC API
-
-- **URL**: `https://api.papermc.io/v2/projects/paper/versions/{version}`
-- **Used for**: Getting Paper builds and download URLs
-
-### Fabric API
-
-- **URL**: `https://meta.fabricmc.net/v2/versions/installer`
-- **Used for**: Getting Fabric installer versions
-
-## Testing Recommendations
-
-1. **Version Checking**:
-
- ```bash
- ./scripts/check-version.sh
- ```
-
-2. **Compatibility Checking**:
-
- ```bash
- ./scripts/check-compatibility.sh 1.21.0
- ```
-
-3. **Server Type Switching**:
-
- ```bash
- ./scripts/switch-server-type.sh paper
- ./scripts/manage.sh start
- ```
-
-4. **Update Process**:
-
- ```bash
- # Test update to a test version first
- ./scripts/manage.sh update 1.20.5
- ```
-
-## Notes
-
-- All scripts require internet connection for API queries
-- Paper and Fabric downloads require valid version numbers
-- Spigot requires BuildTools (not automated)
-- Compatibility checking provides warnings, not hard blocks
-- Backups are automatically created before updates
-- Server type switching stops the server if running
-
-## Next Steps
-
-Remaining P1 tasks:
-
-- Plugin Management (Tasks 2.2.1 - 2.2.4)
- - Plugin installation system
- - Plugin update mechanism
- - Plugin enable/disable
- - Plugin configuration management
-
-These can be implemented next if needed.
diff --git a/docs/archive/IMPLEMENTATION_SUMMARY_docs.md b/docs/archive/IMPLEMENTATION_SUMMARY_docs.md
deleted file mode 100644
index 1f712e9..0000000
--- a/docs/archive/IMPLEMENTATION_SUMMARY_docs.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Critical Features Implementation Summary
-
-This document summarizes the critical P0 features that have been implemented.
-
-## Completed Features (P0 - Critical)
-
-### Backup & Scheduling ✅
-
-#### 1. Cron-based Backup Scheduling (Task 1.1.1)
-
-- **File**: `scripts/backup-scheduler.sh`
-- **Config**: `config/backup-schedule.conf`
-- **Features**:
- - Supports daily, weekly, and monthly schedules
- - Configurable time-of-day execution
- - Logging to `logs/backup-scheduler.log`
- - Automatic cleanup integration
-
-#### 2. Systemd Timer for Backups (Task 1.1.2)
-
-- **Files**:
- - `systemd/minecraft-backup.service`
- - `systemd/minecraft-backup.timer`
- - `scripts/install-backup-timer.sh`
-- **Features**:
- - Systemd-based scheduling (more reliable than cron)
- - Runs daily at 3:00 AM by default
- - Persistent timers (runs missed backups on boot)
- - Easy installation script
-
-#### 3. Backup Retention Policy (Task 1.1.3)
-
-- **File**: `scripts/cleanup-backups.sh`
-- **Config**: `config/backup-retention.conf`
-- **Features**:
- - Keep last N backups regardless of age
- - Separate retention for daily/weekly/monthly backups
- - Automatic classification of backup types
- - Size reporting after cleanup
-
-#### 4. Pre-backup World Save (Task 1.1.4)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Automatically executes `save-all` before backup
- - Works with or without RCON
- - Waits for save completion
- - Error handling
-
-#### 5. Backup Verification (Task 1.1.5)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Verifies backup integrity using tar test
- - Counts files in backup
- - Reports backup size
- - Fails if verification fails
-
-#### 6. Backup Compression (Task 1.1.6)
-
-- **File**: `scripts/manage.sh` (enhanced `create_backup()`)
-- **Features**:
- - Uses gzip compression (tar.gz)
- - Reports compressed size
- - Can be extended for other compression algorithms
-
-### Monitoring & Metrics ✅
-
-#### 7. TPS Monitoring (Task 1.2.1)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Extracts TPS from server logs
- - Stores TPS history in CSV format
- - Logs to `metrics/tps.csv`
-
-#### 8. Memory Usage Monitoring (Task 1.2.2)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Tracks memory usage via Docker stats
- - Records memory consumption over time
- - Logs to `metrics/memory_usage.csv`
- - Can detect memory leaks (via trend analysis)
-
-#### 9. CPU Usage Tracking (Task 1.2.3)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Monitors CPU usage percentage
- - Tracks CPU over time
- - Logs to `metrics/cpu_usage.csv`
- - Can be extended for per-core tracking
-
-#### 10. Player Count Analytics (Task 1.2.4)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Tracks player count over time
- - Extracts from server logs
- - Logs to `metrics/player_count.csv`
- - Can be used for peak hours analysis
-
-#### 11. Server Uptime Tracking (Task 1.2.5)
-
-- **File**: `scripts/monitor.sh`
-- **Features**:
- - Calculates uptime from container start time
- - Tracks uptime in seconds
- - Logs to `metrics/server_uptime.csv`
-
-#### 12. Log Aggregation (Task 1.2.6)
-
-- **Features**:
- - Docker logging with rotation (configured in docker-compose.yml)
- - Logs stored in Docker's JSON log driver
- - Max size: 10MB per file
- - Max files: 3 (30MB total)
-
-#### 13. Health Check Endpoints (Task 1.2.7)
-
-- **File**: `scripts/health-check.sh`
-- **Features**:
- - Checks container status
- - Verifies Java process
- - Checks port listening
- - Monitors CPU and memory thresholds
- - Returns exit codes for automation
- - Integrated into docker-compose.yml healthcheck
-
-#### 14. Prometheus Metrics Export (Task 1.2.8)
-
-- **File**: `scripts/prometheus-exporter.sh`
-- **Features**:
- - Exports metrics in Prometheus format
- - HTTP endpoint support (port 9091)
- - All key metrics exposed
- - Ready for Grafana integration
-
-## New Files Created
-
-### Scripts
-
-1. `scripts/backup-scheduler.sh` - Cron/systemd backup scheduler
-2. `scripts/cleanup-backups.sh` - Backup retention cleanup
-3. `scripts/install-backup-timer.sh` - Systemd timer installer
-4. `scripts/monitor.sh` - Metrics collection script
-5. `scripts/health-check.sh` - Health check script
-6. `scripts/prometheus-exporter.sh` - Prometheus metrics exporter
-
-### Configuration Files
-
-1. `config/backup-schedule.conf` - Backup scheduling configuration
-2. `config/backup-retention.conf` - Backup retention policy
-
-### Systemd Files
-
-1. `systemd/minecraft-backup.service` - Systemd service file
-2. `systemd/minecraft-backup.timer` - Systemd timer file
-
-### Documentation
-
-1. `docs/BACKUP_AND_MONITORING.md` - Comprehensive backup & monitoring guide
-
-## Enhanced Files
-
-1. `scripts/manage.sh` - Enhanced backup function with:
- - Pre-backup world save
- - Backup verification
- - Better error handling
- - Improved RCON command sending
-
-2. `docker-compose.yml` - Enhanced healthcheck configuration
-
-3. `docs/QUICK_REFERENCE.md` - Added new commands
-
-4. `README.md` - Updated features list and backup section
-
-## Usage Examples
-
-### Setup Automated Backups
-
-```bash
-# Install systemd timer
-./scripts/install-backup-timer.sh
-
-# Or configure cron
-crontab -e
-# Add: 0 3 * * * /path/to/minecraft-server/scripts/backup-scheduler.sh
-```
-
-### Run Monitoring
-
-```bash
-# Collect metrics once
-./scripts/monitor.sh
-
-# Set up periodic monitoring (every 5 minutes)
-*/5 * * * * /path/to/minecraft-server/scripts/monitor.sh
-```
-
-### Check Server Health
-
-```bash
-# Run health check
-./scripts/health-check.sh
-
-# Use in monitoring
-if ./scripts/health-check.sh; then
- echo "Server healthy"
-fi
-```
-
-### Export Prometheus Metrics
-
-```bash
-# Output metrics
-./scripts/prometheus-exporter.sh
-
-# Serve on HTTP (requires netcat or HTTP server)
-./scripts/prometheus-exporter.sh --serve
-```
-
-## Next Steps
-
-The following P0 tasks are now complete. Remaining P0 tasks from TASKS.md:
-
-- ✅ All Backup & Scheduling tasks (1.1.1 - 1.1.6)
-- ✅ All Monitoring & Metrics tasks (1.2.1 - 1.2.8)
-
-**Next Priority Tasks (P1):**
-
-- Update Management (Tasks 1.3.1 - 1.3.3)
-- Server Variants & Plugins (Tasks 2.1.1 - 2.2.4)
-
-## Testing Recommendations
-
-1. **Backup Testing**:
- - Test manual backup: `./scripts/manage.sh backup`
- - Test scheduler: `./scripts/backup-scheduler.sh`
- - Test cleanup: `./scripts/cleanup-backups.sh`
- - Verify backups can be restored
-
-2. **Monitoring Testing**:
- - Run monitor script: `./scripts/monitor.sh`
- - Check metrics files in `metrics/` directory
- - Test health check: `./scripts/health-check.sh`
- - Test Prometheus exporter: `./scripts/prometheus-exporter.sh`
-
-3. **Systemd Timer Testing**:
- - Install timer: `./scripts/install-backup-timer.sh`
- - Check status: `sudo systemctl status minecraft-backup.timer`
- - Test run: `sudo systemctl start minecraft-backup.service`
- - Check logs: `sudo journalctl -u minecraft-backup.service`
-
-## Notes
-
-- All scripts are designed to work on Linux/Raspberry Pi OS
-- Scripts use bash and require standard Unix utilities
-- Configuration files use simple shell variable syntax
-- Metrics are stored in CSV format for easy analysis
-- Health checks return proper exit codes for automation
diff --git a/docs/archive/README.md b/docs/archive/README.md
deleted file mode 100644
index 6a5429f..0000000
--- a/docs/archive/README.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Archive Directory
-
-This directory contains archived documentation files that have been consolidated or superseded.
-
-## Archived Files
-
-### Implementation Summaries
-
-- `IMPLEMENTATION_SUMMARY.md` - Consolidated into CHANGELOG.md
-- `IMPLEMENTATION_SUMMARY_P1.md` - Consolidated into CHANGELOG.md
-- `FINAL_IMPLEMENTATION_SUMMARY.md` - Consolidated into CHANGELOG.md
-- `IMPLEMENTATION_SUMMARY_docs.md` - Consolidated into CHANGELOG.md
-
-These files documented feature implementations but have been consolidated into the main CHANGELOG.md for better organization.
-
-### Consolidated Documentation
-
-The following files have been consolidated into comprehensive guides:
-
-- `CI_CD_PIPELINE.md` → Consolidated into [CI_CD.md](../CI_CD.md)
-- `CI_CD_OPTIMIZATIONS.md` → Consolidated into [CI_CD.md](../CI_CD.md)
-- `CI_CD_ENHANCEMENTS.md` → Consolidated into [CI_CD.md](../CI_CD.md)
-- `API_DOCUMENTATION.md` → Consolidated into [API.md](../API.md)
-- `TESTING_COMPLETE.md` → Consolidated into [TESTING.md](../TESTING.md)
-- `TESTING_FINAL_SUMMARY.md` → Consolidated into [TESTING.md](../TESTING.md)
-- `TESTING_ENHANCEMENTS.md` → Consolidated into [TESTING.md](../TESTING.md)
-- `GAMEPLAY_FEATURES_IMPLEMENTED.md` → Consolidated into [MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](../MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) and [CHANGELOG.md](../../CHANGELOG.md)
-- `SUMMARY.md` → Information available in [CHANGELOG.md](../../CHANGELOG.md), [ROADMAP.md](../ROADMAP.md), and [INDEX.md](../INDEX.md)
-- `CONSOLIDATION_NOTES.md` → Historical record of documentation consolidation
-
-### Summary and Checklist Files
-
-- `RPI5_OPTIMIZATIONS_SUMMARY.md` → Quick reference (may be integrated later)
-- `RPI5_ACTION_CHECKLIST.md` → Verification checklist (may be integrated later)
-
-## Current Documentation
-
-For current documentation, see:
-
-- **[docs/INDEX.md](../INDEX.md)** - Documentation index and navigation
-- **[docs/README.md](../README.md)** - Documentation structure guide
-- **[CHANGELOG.md](../../CHANGELOG.md)** - Version history and changes
-- **[README.md](../../README.md)** - Main project documentation
-
-## Note
-
-Archived files are preserved for historical reference but are no longer actively maintained. All information from archived files has been integrated into the current documentation structure.
diff --git a/docs/archive/RPI5_ACTION_CHECKLIST.md b/docs/archive/RPI5_ACTION_CHECKLIST.md
deleted file mode 100644
index a829f92..0000000
--- a/docs/archive/RPI5_ACTION_CHECKLIST.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Raspberry Pi 5 Compatibility - Action Checklist
-
-Quick checklist of steps needed to ensure the project runs on Raspberry Pi 5.
-
-## ✅ Completed
-
-- [x] Dockerfile uses ARM64 base image (`arm64v8/openjdk:21-jdk-slim`)
-- [x] Docker Compose platform specification added (`platform: linux/arm64`)
-- [x] Setup script updated to install Node.js
-- [x] Setup script updated to install Python dependencies
-- [x] Compatibility guide created
-
-## ⚠️ Needs Verification on Actual Hardware
-
-### Critical Verification
-
-- [ ] **Docker Image Build**: Build Docker image on Raspberry Pi 5
-
- ```bash
- docker-compose build
- ```
-
- Expected: Build completes without errors
-
-- [ ] **Server Startup**: Start Minecraft server
-
- ```bash
- ./scripts/manage.sh start
- ```
-
- Expected: Server starts and is accessible
-
-- [ ] **Python API**: Install and test Python API dependencies
-
- ```bash
- cd api
- python3 -m venv venv
- source venv/bin/activate
- pip install -r requirements.txt
- ```
-
- Expected: All packages install successfully
-
-- [ ] **Node.js Web**: Install and build web interface
-
- ```bash
- cd web
- npm install
- npm run build
- ```
-
- Expected: Build completes successfully
-
-- [ ] **Integration Test**: Run full test suite
-
- ```bash
- python3 -m pytest tests/api/ -v
- ```
-
- Expected: All tests pass
-
-### Performance Verification
-
-- [ ] **Memory Usage**: Verify memory usage is within limits
-
- ```bash
- docker stats minecraft-server
- ```
-
- Expected: Memory usage stays within configured limits
-
-- [ ] **CPU Usage**: Monitor CPU usage during gameplay
-
- ```bash
- htop
- ```
-
- Expected: CPU usage is reasonable (<80% average)
-
-- [ ] **Temperature**: Monitor CPU temperature
-
- ```bash
- vcgencmd measure_temp
- ```
-
- Expected: Temperature stays below 80°C under load
-
-## 📝 Documentation Updates Needed
-
-- [ ] Update README with ARM64 build instructions
-- [ ] Add troubleshooting section for ARM64-specific issues
-- [ ] Document performance benchmarks on Pi 5
-- [ ] Add CI/CD testing for ARM64 (optional)
-
-## 🔧 Optional Enhancements
-
-- [ ] Add architecture detection to scripts
-- [ ] Create ARM64-specific optimizations
-- [ ] Add multi-architecture Docker image support
-- [ ] Set up automated testing on ARM64 hardware
-
-## Quick Test Commands
-
-Run these on Raspberry Pi 5 to verify everything works:
-
-```bash
-# 1. Check architecture
-uname -m # Should show: aarch64
-
-# 2. Check Docker
-docker info | grep Architecture # Should show: aarch64
-
-# 3. Build image
-docker-compose build
-
-# 4. Start server
-./scripts/manage.sh start
-
-# 5. Check status
-./scripts/manage.sh status
-
-# 6. Test API (if running)
-curl http://localhost:8080/api/health
-
-# 7. Test web interface (if running)
-curl http://localhost:3000
-```
-
-## Next Steps
-
-1. **Test on actual Raspberry Pi 5 hardware**
-2. **Document any issues found**
-3. **Update compatibility guide with findings**
-4. **Add performance benchmarks**
-5. **Update documentation with Pi-specific notes**
-
----
-
-**Status**: Ready for testing on hardware
-**Last Updated**: 2025-01-27
diff --git a/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md b/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md
deleted file mode 100644
index ccca2db..0000000
--- a/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# Raspberry Pi 5 Optimizations - Quick Summary
-
-Quick reference for all optimizations and enhancements available for Raspberry Pi 5.
-
-## 🚀 Quick Start
-
-### Apply All Optimizations
-
-```bash
-# Run the optimization script
-chmod +x scripts/optimize-rpi5.sh
-./scripts/optimize-rpi5.sh
-```
-
-### Monitor Performance
-
-```bash
-# Run the enhanced monitor
-chmod +x scripts/monitor-rpi5.sh
-./scripts/monitor-rpi5.sh
-```
-
-## 📋 Optimization Categories
-
-### 1. System-Level Optimizations
-
-- ✅ **CPU Governor**: Set to performance mode
-- ✅ **Swap Optimization**: Reduce swap for 4GB Pi
-- ✅ **Kernel Parameters**: Network and memory tuning
-- ✅ **TRIM**: Enable for SD card longevity
-- ✅ **Service Management**: Disable unnecessary services
-
-**Script**: `scripts/optimize-rpi5.sh`
-
-### 2. JVM Optimizations
-
-Enhanced JVM flags in `scripts/start.sh`:
-
-- ✅ String deduplication
-- ✅ Compressed OOPs
-- ✅ Transparent huge pages
-- ✅ Optimized string concatenation
-- ✅ Better random number generation
-
-**File**: `scripts/start.sh` (already updated)
-
-### 3. Docker Optimizations
-
-- ✅ Platform specification (`platform: linux/arm64`)
-- ✅ Resource limits configured
-- ✅ Image cleanup in Dockerfile
-
-**Files**: `docker-compose.yml`, `Dockerfile` (already updated)
-
-### 4. Storage Optimizations
-
-- ✅ TRIM enabled
-- ✅ Log rotation configured
-- ✅ Journal logging optimized
-- ✅ USB power management
-
-**Script**: `scripts/optimize-rpi5.sh`
-
-### 5. Network Optimizations
-
-- ✅ TCP congestion control (BBR)
-- ✅ Increased buffer sizes
-- ✅ Optimized connection limits
-
-**Script**: `scripts/optimize-rpi5.sh`
-
-## 📊 Performance Monitoring
-
-### Enhanced Monitor Script
-
-`scripts/monitor-rpi5.sh` provides:
-
-- CPU temperature and frequency
-- Memory usage
-- Disk usage
-- Docker container stats
-- Network statistics
-- Performance warnings
-
-### Usage
-
-```bash
-./scripts/monitor-rpi5.sh
-```
-
-## 🎯 Expected Performance Improvements
-
-### Before Optimization
-
-- CPU: Variable frequency
-- Memory: Higher swap usage
-- Network: Default TCP settings
-- Storage: No TRIM, more writes
-
-### After Optimization
-
-- CPU: Maximum frequency (performance mode)
-- Memory: Reduced swap usage
-- Network: BBR congestion control, larger buffers
-- Storage: TRIM enabled, reduced writes
-- JVM: Better memory management
-
-### Performance Targets
-
-- **TPS**: 20 TPS (constant)
-- **CPU Usage**: <80% average
-- **Memory**: <90% of allocated
-- **Temperature**: <70°C under load
-- **Network Latency**: <50ms local
-
-## 🔧 Manual Optimizations
-
-### CPU Governor (Manual)
-
-```bash
-sudo apt install cpufrequtils
-echo 'GOVERNOR="performance"' | sudo tee /etc/default/cpufrequtils
-sudo systemctl enable cpufrequtils
-sudo systemctl start cpufrequtils
-```
-
-### Swap Optimization (Manual)
-
-```bash
-# For 4GB Pi
-sudo dphys-swapfile swapoff
-sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=512/' /etc/dphys-swapfile
-sudo dphys-swapfile setup
-sudo dphys-swapfile swapon
-```
-
-### Kernel Parameters (Manual)
-
-```bash
-sudo nano /etc/sysctl.conf
-# Add optimizations from RASPBERRY_PI_OPTIMIZATIONS.md
-sudo sysctl -p
-```
-
-## 📈 Monitoring & Benchmarking
-
-### Before/After Comparison
-
-```bash
-# Before
-./scripts/monitor-rpi5.sh > benchmark-before.txt
-
-# Apply optimizations
-./scripts/optimize-rpi5.sh
-
-# After
-./scripts/monitor-rpi5.sh > benchmark-after.txt
-
-# Compare
-diff benchmark-before.txt benchmark-after.txt
-```
-
-## ⚠️ Important Notes
-
-1. **Reboot Required**: Some optimizations require a reboot
-2. **Temperature**: Monitor CPU temperature after optimizations
-3. **Testing**: Test server performance after applying optimizations
-4. **Backup**: Backup configuration before making changes
-
-## 📚 Full Documentation
-
-For detailed information, see:
-
-- **[RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md)** - Complete optimization guide
-- **[RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md)** - Compatibility guide
-- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Performance troubleshooting
-
-## 🎮 Gameplay Optimizations
-
-### Server Properties
-
-For best performance on Pi 5:
-
-```properties
-view-distance=10
-simulation-distance=8
-max-players=8
-network-compression-threshold=256
-max-tick-time=60000
-```
-
-### Memory Settings
-
-**4GB Pi**:
-
-```yaml
-MEMORY_MIN=1G
-MEMORY_MAX=2G
-```
-
-**8GB Pi**:
-
-```yaml
-MEMORY_MIN=2G
-MEMORY_MAX=4G
-```
-
-## 🔄 Maintenance
-
-### Regular Tasks
-
-1. **Monitor Performance**: Run `monitor-rpi5.sh` weekly
-2. **Check Logs**: Review server logs for issues
-3. **Update System**: Keep Raspberry Pi OS updated
-4. **Clean Backups**: Remove old backups periodically
-
-### Performance Checks
-
-```bash
-# Check temperature
-vcgencmd measure_temp
-
-# Check throttling
-vcgencmd get_throttled
-
-# Check memory
-free -h
-
-# Check disk
-df -h
-```
-
-## 🚨 Troubleshooting
-
-### High Temperature
-
-- Check cooling solution
-- Reduce CPU-intensive operations
-- Lower view distance
-
-### High Memory Usage
-
-- Reduce MEMORY_MAX
-- Lower view distance
-- Restart server periodically
-
-### Performance Issues
-
-- Run optimization script
-- Check for throttling
-- Monitor resource usage
-- Review server.properties
-
----
-
-**Last Updated**: 2025-01-27
-**Status**: Ready for use
diff --git a/docs/archive/SUMMARY.md b/docs/archive/SUMMARY.md
deleted file mode 100644
index 03ff922..0000000
--- a/docs/archive/SUMMARY.md
+++ /dev/null
@@ -1,371 +0,0 @@
-# Project Analysis & Enhancement Summary
-
-> **Note**: This document is a historical record of project analysis. For current project status, see [CHANGELOG.md](../CHANGELOG.md) and [ROADMAP.md](ROADMAP.md).
-
-## Executive Summary
-
-This document summarizes the comprehensive analysis and enhancements made to the Minecraft Server for Raspberry Pi 5 project. The analysis included reviewing all documentation, configuration files, and current project state to create an extensive roadmap, detailed task breakdown, and workspace optimizations.
-
----
-
-## Analysis Performed
-
-### 1. Documentation Review
-- ✅ README.md - Main project documentation
-- ✅ CHANGELOG.md - Version history and planned features
-- ✅ CONTRIBUTING.md - Contribution guidelines
-- ✅ INSTALL.md - Installation instructions
-- ✅ CONFIGURATION_EXAMPLES.md - Configuration examples
-- ✅ QUICK_REFERENCE.md - Command reference
-- ✅ TROUBLESHOOTING.md - Problem solving guide
-
-### 2. Configuration Review
-- ✅ docker-compose.yml - Docker service configuration
-- ✅ Dockerfile - Container image definition
-- ✅ manage.sh - Server management script
-- ✅ start.sh - Server startup script
-- ✅ setup-rpi.sh - Raspberry Pi setup script
-- ✅ server.properties - Server configuration
-- ✅ .gitignore - Git exclusions
-
-### 3. Current State Assessment
-- ✅ Identified implemented features
-- ✅ Documented known limitations
-- ✅ Reviewed planned features from CHANGELOG
-- ✅ Analyzed project structure
-- ✅ Assessed technical debt
-
----
-
-## Deliverables Created
-
-### 1. ROADMAP.md - Comprehensive Development Roadmap
-
-**Contents:**
-- Current state analysis (v1.0.0)
-- Phase 1: Core Enhancements (v1.1.0 - v1.3.0)
- - Automation & Monitoring
- - Server Variants & Plugins
- - Multi-World & Advanced Features
-- Phase 2: Web Interface & Integration (v1.4.0 - v1.6.0)
- - Web Admin Panel
- - Dynamic DNS & Networking
- - Cloud Integration
-- Phase 3: Advanced Features & Enterprise (v2.0.0+)
- - Multi-Server Orchestration
- - Analytics & Intelligence
- - Enterprise Features
-- Phase 4: Community & Ecosystem (v2.3.0+)
- - Community Features
- - Developer Tools
-- Infrastructure & Technical Debt
-- Research & Experimental Features
-- Priority Matrix
-- Success Metrics
-- Timeline Summary (Q1 2025 - Q3 2027)
-
-**Key Features:**
-- 70+ planned features organized by priority
-- Detailed timeline spanning 2+ years
-- Clear priority classification (P0-P3)
-- Success metrics and KPIs
-
-### 2. TASKS.md - Detailed Task Breakdown
-
-**Contents:**
-- 70+ detailed tasks organized by feature
-- Priority classification (P0-P3)
-- Task status tracking
-- Task assignment guidelines
-- Completion status summary
-
-**Task Categories:**
-- Backup & Scheduling (6 tasks)
-- Monitoring & Metrics (8 tasks)
-- Update Management (3 tasks)
-- Server Variants (5 tasks)
-- Plugin Management (4 tasks)
-- Multi-World Support (3 tasks)
-- Web Interface (6 tasks)
-- Authentication & Security (3 tasks)
-- Dynamic DNS (3 tasks)
-- Cloud Backup (2 tasks)
-- Infrastructure (10 tasks)
-
-**Task Details Include:**
-- Task ID and description
-- Implementation steps
-- Testing requirements
-- Documentation updates needed
-- Dependencies
-
-### 3. Workspace Optimizations
-
-#### Configuration Files Created
-
-**Makefile**
-- 15+ convenient commands
-- Server management shortcuts
-- Development commands
-- Testing and build commands
-
-**.editorconfig**
-- Consistent code formatting
-- File-type specific settings
-- Cross-editor compatibility
-
-**.pre-commit-config.yaml**
-- Automated code quality checks
-- Shell script linting
-- YAML/JSON validation
-- Markdown linting
-
-**.vscode/settings.json**
-- Editor configuration
-- File associations
-- Exclude patterns
-- Spell checker configuration
-
-**.vscode/extensions.json**
-- Recommended extensions
-- Docker support
-- Shell script support
-- YAML support
-
-**.vscode/launch.json**
-- Debug configurations
-- Shell script debugging
-
-**.github/workflows/ci.yml**
-- Automated CI pipeline
-- Syntax checking
-- Docker Compose validation
-- Runs on push and PR
-
-#### Enhanced Files
-
-**docker-compose.yml**
-- Environment variable support
-- Healthcheck configuration
-- Logging with rotation
-- Resource limits
-- Custom network configuration
-- Improved flexibility
-
-**.gitignore**
-- Better organization
-- Environment file exclusion
-- Config file exclusions
-- Future-proofing for web panel
-
-#### Documentation Created
-
-**DEVELOPMENT.md**
-- Development environment setup
-- Development workflow
-- Code standards
-- Project structure
-- Common tasks
-- Debugging guide
-- Release process
-
-**WORKSPACE_ENHANCEMENTS.md**
-- Summary of all enhancements
-- New features available
-- Migration notes
-- Benefits for different user types
-
-**config/README.md**
-- Configuration directory structure
-- File descriptions
-- Usage instructions
-
-**scripts/README.md**
-- Scripts directory documentation
-- Best practices
-- Adding new scripts guide
-
----
-
-## Key Improvements
-
-### 1. Project Organization
-- ✅ Clear directory structure
-- ✅ Comprehensive documentation
-- ✅ Consistent code formatting
-- ✅ Automated quality checks
-
-### 2. Developer Experience
-- ✅ VS Code integration
-- ✅ Pre-commit hooks
-- ✅ Makefile for convenience
-- ✅ CI/CD pipeline
-- ✅ Development guide
-
-### 3. Configuration Management
-- ✅ Environment variable support
-- ✅ .env file template
-- ✅ Flexible docker-compose.yml
-- ✅ Configuration directory structure
-
-### 4. Future Planning
-- ✅ Comprehensive roadmap
-- ✅ Detailed task breakdown
-- ✅ Priority classification
-- ✅ Timeline estimates
-- ✅ Success metrics
-
-### 5. Code Quality
-- ✅ Automated linting
-- ✅ Syntax checking
-- ✅ Pre-commit hooks
-- ✅ CI/CD validation
-
----
-
-## Roadmap Highlights
-
-### Phase 1 (v1.1.0 - v1.3.0) - Q1-Q3 2025
-**Focus: Core Enhancements**
-- Automated backup scheduling
-- Performance monitoring dashboard
-- Automatic updates
-- Paper/Spigot server support
-- Plugin management
-- Multi-world support
-
-### Phase 2 (v1.4.0 - v1.6.0) - Q4 2025 - Q2 2026
-**Focus: Web Interface & Integration**
-- Web-based admin panel
-- Dynamic DNS integration
-- Cloud backup integration
-- Mobile app
-
-### Phase 3 (v2.0.0+) - Q3 2026+
-**Focus: Advanced Features**
-- Multi-server orchestration
-- Analytics & intelligence
-- Enterprise features
-- Community features
-
----
-
-## Task Statistics
-
-### By Priority
-- **P0 (Critical)**: 15 tasks
-- **P1 (High)**: 25 tasks
-- **P2 (Medium)**: 20 tasks
-- **P3 (Low)**: 10 tasks
-
-### By Phase
-- **Phase 1**: 40 tasks
-- **Phase 2**: 15 tasks
-- **Infrastructure**: 10 tasks
-- **Total**: 70 tasks
-
-### Completion Status
-- **Completed**: 0 (baseline established)
-- **In Progress**: 0
-- **Pending**: 70
-
----
-
-## Next Steps
-
-### Immediate Actions
-1. ✅ Review ROADMAP.md for project direction
-2. ✅ Review TASKS.md for specific work items
-3. ✅ Set up development environment (see DEVELOPMENT.md)
-4. ✅ Create .env file from template
-5. ✅ Install pre-commit hooks (optional)
-6. ✅ Test workspace enhancements
-
-### Short-term (Next Sprint)
-1. Start with P0 tasks from TASKS.md
-2. Implement automated backup scheduling
-3. Add performance monitoring
-4. Set up CI/CD pipeline testing
-
-### Long-term
-1. Follow roadmap phases
-2. Regular roadmap reviews (quarterly)
-3. Update tasks as features are completed
-4. Gather community feedback
-
----
-
-## Benefits Summary
-
-### For Users
-- ✅ Better documentation
-- ✅ Clearer project direction
-- ✅ More reliable updates
-- ✅ Easier configuration
-
-### For Developers
-- ✅ Comprehensive roadmap
-- ✅ Detailed task breakdown
-- ✅ Better development environment
-- ✅ Clear contribution guidelines
-
-### For Maintainers
-- ✅ Organized project structure
-- ✅ Automated quality checks
-- ✅ Clear priorities
-- ✅ Easier maintenance
-
----
-
-## Files Created/Modified
-
-### New Files (15)
-1. ROADMAP.md
-2. TASKS.md
-3. DEVELOPMENT.md
-4. WORKSPACE_ENHANCEMENTS.md
-5. SUMMARY.md (this file)
-6. Makefile
-7. .editorconfig
-8. .pre-commit-config.yaml
-9. .vscode/settings.json
-10. .vscode/extensions.json
-11. .vscode/launch.json
-12. .github/workflows/ci.yml
-13. config/README.md
-14. scripts/README.md
-15. .env.example (template - create manually)
-
-### Modified Files (3)
-1. docker-compose.yml (enhanced)
-2. .gitignore (improved)
-3. README.md (updated with new docs)
-
----
-
-## Conclusion
-
-This comprehensive analysis and enhancement effort has:
-
-1. **Created a clear roadmap** spanning 2+ years with 70+ features
-2. **Organized tasks** into actionable items with priorities
-3. **Optimized the workspace** for better development experience
-4. **Enhanced configuration** for flexibility and maintainability
-5. **Improved documentation** for all user types
-
-The project now has:
-- Clear direction and priorities
-- Detailed implementation plans
-- Better development tools
-- Comprehensive documentation
-- Automated quality checks
-
-All enhancements are backward compatible and can be adopted gradually.
-
----
-
-**Analysis Date**: 2025-01-XX
-**Analyst**: AI Assistant
-**Project Version**: 1.0.0
-**Next Review**: Quarterly
-
diff --git a/docs/archive/TESTING_COMPLETE.md b/docs/archive/TESTING_COMPLETE.md
deleted file mode 100644
index 09b4da2..0000000
--- a/docs/archive/TESTING_COMPLETE.md
+++ /dev/null
@@ -1,403 +0,0 @@
-# Complete Testing Guide
-
-This document provides a comprehensive overview of all testing capabilities in the Minecraft Server Management project.
-
-## Test Coverage Summary
-
-### Current Coverage Status
-
-| Test Type | Coverage | Target | Status |
-| -------------------- | -------- | ------- | ------------- |
-| API Tests | ~65% | 70% | ✅ Good |
-| Component Tests | ~60% | 70% | ✅ Good |
-| Integration Tests | ~50% | 60% | ✅ Good |
-| E2E Tests | ~45% | 50% | ✅ Good |
-| Unit Tests (Scripts) | ~50% | 60% | ⚠️ Needs work |
-| **Overall** | **~60%** | **70%** | ✅ **Good** |
-
-## Test Types
-
-### 1. Unit Tests
-
-#### Python Unit Tests
-
-- **Location**: `tests/api/`
-- **Framework**: pytest
-- **Coverage**: API endpoints, analytics processor algorithms
-
-**Files**:
-
-- `test_api.py` - Basic API tests
-- `test_analytics.py` - Analytics endpoint tests
-- `test_api_comprehensive.py` - Comprehensive API tests
-- `test_analytics_processor.py` - Analytics algorithm tests
-- `test_auth.py` - Authentication tests
-- `test_rbac.py` - RBAC tests
-- `test_backup_management.py` - Backup tests
-- `test_config_files.py` - Config file tests
-
-#### Bash Script Unit Tests
-
-- **Location**: `tests/unit/`
-- **Framework**: BATS
-- **Coverage**: Management scripts
-
-**Files**:
-
-- `test-manage.sh` - Server management script tests
-- `test-backup-scheduler.sh` - Backup scheduler tests
-- `test-log-manager.sh` - Log manager tests
-- `test-analytics-collector.sh` - Analytics collector tests
-
-### 2. Component Tests
-
-#### React Component Tests
-
-- **Location**: `web/src/pages/__tests__/` and `web/src/components/__tests__/`
-- **Framework**: Vitest + React Testing Library
-- **Coverage**: UI components
-
-**Files**:
-
-- `Analytics.test.jsx` - Analytics component (15+ tests)
-- `Dashboard.test.jsx` - Dashboard component
-- `Backups.test.jsx` - Backups component (NEW)
-- `Players.test.jsx` - Players component (NEW)
-- `Worlds.test.jsx` - Worlds component (NEW)
-- `Login.test.jsx` - Login component
-- `Register.test.jsx` - Registration component
-- And more...
-
-### 3. Integration Tests
-
-#### API Integration Tests
-
-- **Location**: `tests/integration/`
-- **Framework**: BATS
-- **Coverage**: System integration
-
-**Files**:
-
-- `test-backup-system.sh` - Backup system integration
-- `test-monitoring.sh` - Monitoring integration
-- `test-plugin-management.sh` - Plugin management
-- `test-rcon.sh` - RCON integration
-- `test-world-management.sh` - World management
-- `test-analytics.sh` - Analytics system integration (NEW)
-
-#### React Integration Tests
-
-- **Location**: `web/src/test/integration/`
-- **Framework**: Vitest
-- **Coverage**: Component workflows
-
-**Files**:
-
-- `analytics.integration.test.jsx` - Analytics workflow (NEW)
-- `dashboard.integration.test.jsx` - Dashboard workflow
-- `logs.integration.test.jsx` - Logs workflow
-
-### 4. End-to-End Tests
-
-#### API E2E Tests
-
-- **Location**: `tests/e2e/`
-- **Framework**: BATS
-- **Coverage**: Complete workflows
-
-**Files**:
-
-- `test-api-workflow.sh` - API workflow
-- `test-backup-workflow.sh` - Backup workflow
-- `test-server-lifecycle.sh` - Server lifecycle
-- `test-analytics-workflow.sh` - Analytics workflow (NEW)
-- `test-complete-user-journey.sh` - Complete user journey (NEW)
-- `test-web-ui-workflow.sh` - Web UI workflow (NEW)
-
-#### Browser E2E Tests
-
-- **Location**: `tests/e2e/browser/`
-- **Framework**: Playwright
-- **Coverage**: Real browser testing
-
-**Files**:
-
-- `analytics.spec.js` - Analytics page browser tests (NEW)
-- `user-journey.spec.js` - User journey browser tests (NEW)
-- `visual-regression.spec.js` - Visual regression tests (NEW)
-
-### 5. Accessibility Tests
-
-#### A11y Tests
-
-- **Location**: `web/src/test/a11y.test.jsx`
-- **Framework**: jest-axe
-- **Coverage**: WCAG compliance
-
-**Tests**:
-
-- Analytics page accessibility
-- Dashboard accessibility
-- Backups page accessibility
-- Players page accessibility
-- Worlds page accessibility
-- Login page accessibility
-- Form label validation
-
-### 6. Visual Regression Tests
-
-#### Visual Tests
-
-- **Location**: `tests/e2e/browser/visual-regression.spec.js`
-- **Framework**: Playwright
-- **Coverage**: UI visual consistency
-
-**Tests**:
-
-- Dashboard visual snapshot
-- Analytics page visual snapshot
-- Backups page visual snapshot
-- Players page visual snapshot
-- Worlds page visual snapshot
-- Login page visual snapshot
-
-## Running Tests
-
-### All Tests
-
-```bash
-# Run all test suites
-./scripts/run-tests.sh
-```
-
-### Python Tests
-
-```bash
-# All Python tests
-pytest tests/api/ -v
-
-# With coverage
-pytest tests/api/ --cov=api --cov-report=html
-
-# Specific test file
-pytest tests/api/test_analytics.py -v
-```
-
-### Component Tests
-
-```bash
-cd web
-npm test # All tests
-npm test Analytics # Analytics tests
-npm test Backups # Backups tests
-npm test Players # Players tests
-npm test Worlds # Worlds tests
-npm run test:coverage # With coverage
-```
-
-### Integration Tests
-
-```bash
-# Bash integration tests
-bats tests/integration/test-analytics.sh
-
-# React integration tests
-cd web
-npm test integration
-```
-
-### E2E Tests
-
-```bash
-# API E2E tests
-bats tests/e2e/test-complete-user-journey.sh
-bats tests/e2e/test-web-ui-workflow.sh
-
-# Browser E2E tests
-cd web
-npx playwright test
-
-# Visual regression
-npx playwright test tests/e2e/browser/visual-regression.spec.js
-```
-
-### Accessibility Tests
-
-```bash
-cd web
-npm test a11y
-```
-
-## Test Configuration
-
-### Vitest Configuration
-
-- **File**: `web/vitest.config.js`
-- **Environment**: jsdom
-- **Coverage**: v8 provider
-- **Setup**: `web/src/test/setup.js`
-
-### Playwright Configuration
-
-- **File**: `playwright.config.js`
-- **Browsers**: Chromium, Firefox, WebKit
-- **Base URL**:
-- **Screenshots**: On failure
-
-### Pytest Configuration
-
-- **File**: `tests/api/pytest.ini`
-- **Markers**: unit, integration, api, slow
-- **Coverage**: pytest-cov
-
-## Test Best Practices
-
-### Writing Tests
-
-1. **Follow AAA Pattern**
-
- ```javascript
- // Arrange
- const mockData = {...};
-
- // Act
- render();
-
- // Assert
- expect(screen.getByText('Expected')).toBeInTheDocument();
- ```
-
-2. **Test User Behavior**
-
- - Test what users see and do
- - Avoid testing implementation details
- - Use semantic queries
-
-3. **Mock External Dependencies**
-
- ```javascript
- vi.mock('../services/api');
- ```
-
-4. **Clean Up**
-
- ```javascript
- afterEach(() => {
- vi.clearAllMocks();
- });
- ```
-
-### Test Organization
-
-```
-tests/
-├── api/ # Python API tests
-├── unit/ # Bash script tests
-├── integration/ # Integration tests
-├── e2e/ # E2E tests
-│ └── browser/ # Browser automation
-└── helpers/ # Test utilities
-
-web/src/
-├── pages/__tests__/ # Component tests
-├── components/__tests__/ # Component tests
-└── test/ # Test utilities & integration
- ├── integration/ # Integration tests
- ├── mocks/ # Mock handlers
- └── a11y.test.jsx # Accessibility tests
-```
-
-## Coverage Goals
-
-### Current Status
-
-- **Overall**: ~60% coverage
-- **API**: ~65% coverage
-- **Components**: ~60% coverage
-- **E2E**: ~45% coverage
-
-### Target Goals
-
-- **Overall**: 70%+ coverage
-- **API**: 75%+ coverage
-- **Components**: 70%+ coverage
-- **E2E**: 50%+ coverage
-
-## CI/CD Integration
-
-### GitHub Actions
-
-- Runs on pull requests
-- Runs on pushes to main
-- Generates coverage reports
-- Publishes test results
-
-### Test Workflows
-
-- `.github/workflows/tests.yml` - Main test workflow
-- `.github/workflows/coverage.yml` - Coverage reporting
-
-## New Test Files Added
-
-### Analytics Tests
-
-1. ✅ `tests/api/test_analytics.py` - API endpoint tests
-2. ✅ `tests/api/test_analytics_processor.py` - Algorithm tests (NEW)
-3. ✅ `web/src/pages/__tests__/Analytics.test.jsx` - Component tests
-4. ✅ `web/src/test/integration/analytics.integration.test.jsx` - Integration tests
-5. ✅ `tests/integration/test-analytics.sh` - System integration
-6. ✅ `tests/e2e/test-analytics-workflow.sh` - E2E workflow
-
-### Component Tests
-
-7. ✅ `web/src/pages/__tests__/Backups.test.jsx` - Backups component (NEW)
-8. ✅ `web/src/pages/__tests__/Players.test.jsx` - Players component (NEW)
-9. ✅ `web/src/pages/__tests__/Worlds.test.jsx` - Worlds component (NEW)
-
-### E2E Tests
-
-10. ✅ `tests/e2e/test-complete-user-journey.sh` - Complete journey
-11. ✅ `tests/e2e/test-web-ui-workflow.sh` - Web UI workflow
-12. ✅ `tests/e2e/browser/analytics.spec.js` - Browser tests (NEW)
-13. ✅ `tests/e2e/browser/user-journey.spec.js` - Browser journey (NEW)
-
-### Accessibility & Visual
-
-14. ✅ `web/src/test/a11y.test.jsx` - Accessibility tests (NEW)
-15. ✅ `tests/e2e/browser/visual-regression.spec.js` - Visual tests (NEW)
-
-## Test Statistics
-
-- **Total Test Files**: 30+
-- **Total Test Cases**: 200+
-- **Component Tests**: 50+
-- **API Tests**: 80+
-- **E2E Tests**: 40+
-- **Integration Tests**: 20+
-- **Accessibility Tests**: 6+
-- **Visual Tests**: 6+
-
-## Next Steps
-
-### Completed ✅
-
-1. ✅ Analytics processor unit tests
-2. ✅ Component tests for Backups, Players, Worlds
-3. ✅ Visual regression tests
-4. ✅ Accessibility tests
-5. ✅ Browser automation with Playwright
-
-### Future Enhancements
-
-1. Performance tests
-2. Load tests
-3. Security tests
-4. Cross-browser compatibility tests
-5. Mobile responsive tests
-
-## See Also
-
-- [Testing Guide](TESTING.md)
-- [Web UI Testing Guide](WEB_UI_TESTING.md)
-- [Test Coverage Guide](TEST_COVERAGE.md)
-- [Analytics Tests](ANALYTICS_TESTS.md)
diff --git a/docs/archive/TESTING_ENHANCEMENTS.md b/docs/archive/TESTING_ENHANCEMENTS.md
deleted file mode 100644
index 437c323..0000000
--- a/docs/archive/TESTING_ENHANCEMENTS.md
+++ /dev/null
@@ -1,372 +0,0 @@
-# Testing Framework Enhancements
-
-This document describes the comprehensive enhancements made to the testing framework.
-
-## Overview
-
-The testing framework has been significantly enhanced with new utilities, tools, and capabilities to improve test quality, coverage, and developer experience.
-
-## New Features
-
-### 1. Test Data Factories
-
-**Location**: `tests/api/factories.py`
-
-Reusable factories for creating test data:
-
-- `generate_api_key()` - Generate random API keys
-- `create_user_data()` - Create test user data
-- `create_api_key_data()` - Create test API key data
-- `create_backup_metadata()` - Create backup metadata
-- `create_server_properties()` - Generate server.properties content
-- `create_whitelist_entry()` - Create whitelist entries
-- `create_ban_entry()` - Create ban entries
-- `create_world_data()` - Create world data
-- `create_plugin_data()` - Create plugin data
-
-**Usage**:
-
-```python
-from tests.api.factories import create_user_data, create_api_key_data
-
-user = create_user_data(username="testuser", role="admin")
-api_key = create_api_key_data(name="test-key")
-```
-
-### 2. Enhanced Test Fixtures
-
-**Location**: `tests/api/conftest.py`
-
-New fixtures added:
-
-- `test_user_data` - Factory-generated user data
-- `test_api_key_data` - Factory-generated API key data
-- `test_backup_metadata` - Factory-generated backup metadata
-- `test_server_properties` - Server.properties content
-- `test_data_dir` - Temporary data directory with subdirectories
-- `test_backup_dir` - Temporary backup directory
-- `mock_docker` - Mock Docker operations
-- `mock_file_system` - Mock file system operations
-- `mock_network` - Mock network operations
-- `isolated_test_env` - Isolated test environment with directories
-
-**Usage**:
-
-```python
-def test_something(test_user_data, test_data_dir, mock_docker):
- # Use fixtures in tests
- user = test_user_data
- data_path = test_data_dir / "world"
-```
-
-### 3. Test Parallelization
-
-**Configuration**: `tests/api/pytest.ini`
-
-Tests can now run in parallel using `pytest-xdist`:
-
-```bash
-# Run tests in parallel (auto-detects CPU count)
-pytest -n auto
-
-# Or specify number of workers
-pytest -n 4
-```
-
-**Makefile command**:
-
-```bash
-make test-api-parallel
-```
-
-### 4. Enhanced Test Reporting
-
-**Configuration**: `tests/api/pytest.ini`
-
-Multiple report formats now available:
-
-- **Terminal**: `--cov-report=term-missing` (default)
-- **HTML**: `--cov-report=html:htmlcov`
-- **JSON**: `--cov-report=json:coverage.json`
-- **XML**: `--cov-report=xml:coverage.xml` (for CI/CD)
-- **JUnit**: Built-in JUnit XML support
-
-Reports are automatically generated when running tests with coverage.
-
-### 5. Performance Testing Utilities
-
-**Location**: `tests/api/performance_utils.py`
-
-Utilities for performance and load testing:
-
-- `PerformanceTimer` - Context manager for timing operations
-- `measure_execution_time()` - Measure function execution time
-- `run_load_test()` - Run load tests with threading
-- `print_performance_report()` - Format and print performance results
-- `benchmark_endpoint()` - Benchmark API endpoints
-
-**Usage**:
-
-```python
-from tests.api.performance_utils import PerformanceTimer, run_load_test
-
-# Time a single operation
-with PerformanceTimer("Operation") as timer:
- do_something()
-print(f"Duration: {timer.get_duration()}s")
-
-# Load test
-results = run_load_test(my_function, num_requests=100, num_threads=10)
-print_performance_report(results)
-```
-
-**Example Test**:
-
-```python
-@pytest.mark.performance
-def test_endpoint_performance(client):
- results = benchmark_endpoint(
- client, 'GET', '/api/health',
- num_requests=100, num_threads=10
- )
- assert results['avg_duration'] < 0.1
-```
-
-### 6. API Contract Testing
-
-**Location**: `tests/api/contract_test_utils.py`
-
-Utilities for validating API contracts against OpenAPI schema:
-
-- `load_openapi_schema()` - Load OpenAPI schema from file
-- `validate_response_schema()` - Validate API response against schema
-- `validate_request_schema()` - Validate API request against schema
-- `get_endpoint_schema()` - Get schema definition for endpoint
-
-**Usage**:
-
-```python
-from tests.api.contract_test_utils import validate_response_schema
-
-response = client.get('/api/health')
-data = json.loads(response.data)
-is_valid, error = validate_response_schema(data, '/api/health', 'GET', 200)
-assert is_valid
-```
-
-**Example Test**:
-
-```python
-@pytest.mark.contract
-def test_endpoint_contract(client):
- response = client.get('/api/health')
- data = json.loads(response.data)
- is_valid, error = validate_response_schema(data, '/api/health', 'GET', 200)
- assert is_valid, error
-```
-
-### 7. Coverage Gap Analysis
-
-**Location**: `scripts/analyze-coverage-gaps.sh`
-
-Tool to identify untested code paths and suggest improvements:
-
-```bash
-# Analyze coverage gaps
-./scripts/analyze-coverage-gaps.sh analyze
-
-# Show detailed gaps
-./scripts/analyze-coverage-gaps.sh detailed
-
-# Get improvement suggestions
-./scripts/analyze-coverage-gaps.sh suggest
-```
-
-**Makefile commands**:
-
-```bash
-make coverage-gaps
-make coverage-gaps-detailed
-make coverage-suggestions
-```
-
-The tool:
-
-- Identifies files with coverage < 80%
-- Shows missing line numbers
-- Suggests test improvements
-- Generates detailed reports
-
-### 8. Enhanced Test Isolation
-
-**Location**: `tests/api/conftest.py`
-
-Improved test isolation with:
-
-- Automatic cleanup via `tmp_path` fixture
-- Isolated test environments with `isolated_test_env` fixture
-- Mock fixtures that don't interfere with each other
-- Better teardown between tests
-
-## New Test Files
-
-### Performance Tests
-
-**Location**: `tests/api/test_performance.py`
-
-Performance tests for API endpoints:
-
-- Health endpoint performance
-- Load testing
-- Response time validation
-- Throughput measurement
-
-Run with:
-
-```bash
-pytest -m performance
-# or
-make test-api-performance
-```
-
-### Contract Tests
-
-**Location**: `tests/api/test_contract.py`
-
-API contract validation tests:
-
-- Response schema validation
-- Request schema validation
-- OpenAPI compliance
-
-Run with:
-
-```bash
-pytest -m contract
-# or
-make test-api-contract
-```
-
-### Factory Tests
-
-**Location**: `tests/api/test_factories.py`
-
-Tests for test data factories to ensure they work correctly.
-
-## Updated Configuration
-
-### pytest.ini
-
-Enhanced with:
-
-- Multiple coverage report formats
-- New test markers (performance, contract, e2e)
-- Better error reporting
-
-### Makefile
-
-New commands:
-
-- `make test-api-parallel` - Run tests in parallel
-- `make test-api-performance` - Run performance tests
-- `make test-api-contract` - Run contract tests
-- `make test-factories` - Test factory utilities
-- `make coverage-gaps` - Analyze coverage gaps
-- `make coverage-gaps-detailed` - Detailed gap analysis
-- `make coverage-suggestions` - Get improvement suggestions
-
-### Test Requirements
-
-**Location**: `api/requirements-test.txt`
-
-New testing dependencies:
-
-- `pytest-xdist` - Parallel test execution
-- `pytest-mock` - Enhanced mocking
-- `pytest-timeout` - Test timeout support
-- `jsonschema` - Schema validation
-- `pyyaml` - YAML parsing for OpenAPI
-
-Install with:
-
-```bash
-pip install -r api/requirements-test.txt
-```
-
-## Usage Examples
-
-### Running Tests with New Features
-
-```bash
-# Run all tests with parallel execution
-make test-api-parallel
-
-# Run performance tests
-make test-api-performance
-
-# Run contract tests
-make test-api-contract
-
-# Analyze coverage gaps
-make coverage-gaps
-
-# Generate all coverage reports
-make coverage
-```
-
-### Writing Tests with New Utilities
-
-```python
-import pytest
-from tests.api.factories import create_user_data
-from tests.api.performance_utils import PerformanceTimer
-
-@pytest.mark.performance
-def test_user_creation_performance(client, test_user_data):
- with PerformanceTimer("User creation") as timer:
- response = client.post('/api/auth/register', json=test_user_data)
- assert response.status_code == 200
- assert timer.get_duration() < 0.5
-```
-
-## Benefits
-
-1. **Faster Test Execution**: Parallel execution reduces test time
-2. **Better Coverage Analysis**: Gap analysis identifies untested code
-3. **Performance Monitoring**: Built-in performance testing utilities
-4. **API Contract Validation**: Ensures API compliance with OpenAPI
-5. **Reusable Test Data**: Factories reduce test setup code
-6. **Better Reporting**: Multiple report formats for different needs
-7. **Improved Isolation**: Better test isolation prevents interference
-
-## Migration Guide
-
-### Existing Tests
-
-No changes required for existing tests. New utilities are optional.
-
-### New Tests
-
-Use new utilities for:
-
-- Creating test data (use factories)
-- Performance testing (use performance utilities)
-- Contract validation (use contract utilities)
-- Load testing (use load test functions)
-
-## Future Enhancements
-
-Potential future improvements:
-
-1. **Mutation Testing**: Add mutation testing for test quality
-2. **Visual Regression**: Enhanced visual regression testing
-3. **API Fuzzing**: Automated API fuzzing tests
-4. **Database Testing**: Database-specific test utilities
-5. **Integration Test Helpers**: More integration test utilities
-
-## Resources
-
-- [pytest Documentation](https://docs.pytest.org/)
-- [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/)
-- [Coverage.py Documentation](https://coverage.readthedocs.io/)
-- [JSON Schema Validation](https://python-jsonschema.readthedocs.io/)
diff --git a/docs/archive/TESTING_FINAL_SUMMARY.md b/docs/archive/TESTING_FINAL_SUMMARY.md
deleted file mode 100644
index c8bd024..0000000
--- a/docs/archive/TESTING_FINAL_SUMMARY.md
+++ /dev/null
@@ -1,243 +0,0 @@
-# Final Testing Implementation Summary
-
-## ✅ All Optional Next Steps Completed
-
-All requested test improvements have been successfully implemented!
-
-## What Was Added
-
-### 1. Analytics Processor Unit Tests ✅
-
-**File**: `tests/api/test_analytics_processor.py`
-
-**30+ comprehensive unit tests** covering:
-- ✅ Data loading (empty files, filtering, invalid JSON)
-- ✅ Trend calculation (increasing, decreasing, stable)
-- ✅ Anomaly detection (Z-score algorithm, severity)
-- ✅ Predictions (linear prediction, confidence)
-- ✅ Player behavior (unique players, peak hours)
-- ✅ Report generation (structure, warnings, recommendations)
-- ✅ Performance trends analysis
-
-### 2. Component Tests for Backups, Players, Worlds ✅
-
-**Files**:
-- `web/src/pages/__tests__/Backups.test.jsx` - **12+ tests**
-- `web/src/pages/__tests__/Players.test.jsx` - **8+ tests**
-- `web/src/pages/__tests__/Worlds.test.jsx` - **6+ tests**
-
-**Coverage**:
-- Component rendering
-- Loading and empty states
-- User interactions
-- Error handling
-- API integration
-
-### 3. Visual Regression Tests ✅
-
-**File**: `tests/e2e/browser/visual-regression.spec.js`
-
-**6 visual snapshot tests**:
-- Dashboard
-- Analytics
-- Backups
-- Players
-- Worlds
-- Login
-
-**Framework**: Playwright with screenshot comparison
-
-### 4. Accessibility Tests ✅
-
-**File**: `web/src/test/a11y.test.jsx`
-
-**7 accessibility tests** using jest-axe:
-- Analytics page (WCAG compliance)
-- Dashboard page
-- Backups page
-- Players page
-- Worlds page
-- Login page
-- Form label validation
-
-### 5. Browser Automation with Playwright ✅
-
-**Files**:
-- `playwright.config.js` - Configuration
-- `tests/e2e/browser/analytics.spec.js` - Analytics browser tests
-- `tests/e2e/browser/user-journey.spec.js` - User journey tests
-- `tests/e2e/browser/visual-regression.spec.js` - Visual tests
-- `.github/workflows/playwright.yml` - CI/CD integration
-
-**Features**:
-- Real browser testing (Chromium, Firefox, WebKit)
-- Complete user workflows
-- Visual regression
-- Cross-browser compatibility
-
-## Final Coverage Statistics
-
-### Overall Coverage
-- **Before**: ~51%
-- **After**: **~70%+** ✅
-- **Improvement**: +19%
-
-### By Area
-| Area | Before | After | Improvement |
-|------|--------|-------|-------------|
-| API Tests | ~40% | ~75% | +35% |
-| Component Tests | ~20% | ~70% | +50% |
-| E2E Tests | ~15% | ~55% | +40% |
-| Analytics | 0% | ~95% | +95% |
-| Unit Tests (Scripts) | ~40% | ~50% | +10% |
-
-### Test Count
-- **Total Test Files**: 30+
-- **Total Test Cases**: 250+
-- **New Test Cases Added**: 100+
-
-## New Test Files Summary
-
-### Analytics Tests (8 files)
-1. ✅ `tests/api/test_analytics.py`
-2. ✅ `tests/api/test_analytics_processor.py`
-3. ✅ `web/src/pages/__tests__/Analytics.test.jsx`
-4. ✅ `web/src/test/integration/analytics.integration.test.jsx`
-5. ✅ `tests/integration/test-analytics.sh`
-6. ✅ `tests/e2e/test-analytics-workflow.sh`
-7. ✅ `tests/unit/test-analytics-collector.sh`
-8. ✅ `tests/e2e/browser/analytics.spec.js`
-
-### Component Tests (3 files)
-9. ✅ `web/src/pages/__tests__/Backups.test.jsx`
-10. ✅ `web/src/pages/__tests__/Players.test.jsx`
-11. ✅ `web/src/pages/__tests__/Worlds.test.jsx`
-
-### E2E Tests (5 files)
-12. ✅ `tests/e2e/test-complete-user-journey.sh`
-13. ✅ `tests/e2e/test-web-ui-workflow.sh`
-14. ✅ `tests/e2e/browser/user-journey.spec.js`
-15. ✅ `tests/e2e/browser/visual-regression.spec.js`
-16. ✅ `tests/api/test_api_comprehensive.py`
-
-### Accessibility & Visual (2 files)
-17. ✅ `web/src/test/a11y.test.jsx`
-18. ✅ `tests/e2e/browser/visual-regression.spec.js`
-
-## Running Tests
-
-### Quick Commands
-```bash
-# All tests
-make test
-
-# Specific suites
-make test-api # Python API tests
-make test-web # React component tests
-make test-web-a11y # Accessibility tests
-make test-playwright # Browser automation
-make test-e2e # End-to-end tests
-```
-
-### Detailed Commands
-```bash
-# Python tests
-pytest tests/api/ -v
-pytest tests/api/test_analytics_processor.py -v
-
-# Component tests
-cd web && npm test
-cd web && npm test Backups
-cd web && npm test Players
-cd web && npm test Worlds
-
-# Accessibility
-cd web && npm run test:a11y
-
-# Browser tests
-cd web && npm run test:playwright
-cd web && npx playwright test --ui
-
-# Visual regression
-cd web && npx playwright test tests/e2e/browser/visual-regression.spec.js
-```
-
-## Test Quality
-
-### ✅ Coverage Goals Met
-- Overall: 70%+ ✅ (target: 70%)
-- API: 75%+ ✅ (target: 75%)
-- Components: 70%+ ✅ (target: 70%)
-- E2E: 55%+ ✅ (target: 50%)
-- Analytics: 95%+ ✅ (target: 80%)
-
-### ✅ Test Reliability
-- Flaky tests: 0
-- Failing tests: 0
-- Skipped tests: Only E2E (require running server)
-
-### ✅ Test Execution Speed
-- Unit tests: < 5 seconds
-- Component tests: < 10 seconds
-- Integration tests: < 15 seconds
-- Browser tests: < 60 seconds
-
-## Documentation
-
-### New Documentation
-1. ✅ `docs/TESTING_COMPLETE.md` - Complete testing guide
-2. ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide
-3. ✅ `docs/TEST_COVERAGE.md` - Coverage guide
-4. ✅ `tests/COMPLETE_TEST_SUMMARY.md` - Complete summary
-5. ✅ `tests/e2e/browser/README.md` - Browser tests guide
-
-## CI/CD Integration
-
-### GitHub Actions
-- ✅ Main test workflow (`.github/workflows/tests.yml`)
-- ✅ Coverage reporting (`.github/workflows/coverage.yml`)
-- ✅ Playwright tests (`.github/workflows/playwright.yml`) - NEW
-
-### Automated Testing
-- Runs on all pull requests
-- Runs on pushes to main
-- Generates coverage reports
-- Publishes test results
-- Screenshots on failure
-
-## Key Achievements
-
-### ✅ Comprehensive Coverage
-- All major features tested
-- Analytics system fully covered
-- Web UI components tested
-- E2E workflows validated
-
-### ✅ Quality Assurance
-- WCAG accessibility compliance
-- Visual regression prevention
-- Cross-browser compatibility
-- Error handling validation
-
-### ✅ Developer Experience
-- Easy test execution
-- Clear organization
-- Comprehensive documentation
-- CI/CD integration
-
-## Summary
-
-**Status**: ✅ **ALL OPTIONAL NEXT STEPS COMPLETED!**
-
-- ✅ Analytics processor unit tests
-- ✅ Component tests (Backups, Players, Worlds)
-- ✅ Visual regression tests
-- ✅ Accessibility tests
-- ✅ Browser automation (Playwright)
-
-**Final Coverage**: **~70%+ overall** (exceeds 60% target)
-
-**Test Cases**: **250+ comprehensive tests**
-
-**Quality**: Production-ready test suite with comprehensive coverage!
-
diff --git a/playwright.config.js b/playwright.config.js
deleted file mode 100644
index 952c2a2..0000000
--- a/playwright.config.js
+++ /dev/null
@@ -1,41 +0,0 @@
-import { defineConfig, devices } from '@playwright/test';
-
-/**
- * Playwright configuration for browser automation tests
- * @see https://playwright.dev/docs/test-configuration
- */
-export default defineConfig({
- testDir: './tests/e2e/browser',
- fullyParallel: true,
- forbidOnly: !!process.env.CI,
- retries: process.env.CI ? 2 : 0,
- workers: process.env.CI ? 1 : undefined,
- reporter: 'html',
- use: {
- baseURL: process.env.WEB_URL || 'http://localhost:5173',
- trace: 'on-first-retry',
- screenshot: 'only-on-failure',
- },
-
- projects: [
- {
- name: 'chromium',
- use: { ...devices['Desktop Chrome'] },
- },
- {
- name: 'firefox',
- use: { ...devices['Desktop Firefox'] },
- },
- {
- name: 'webkit',
- use: { ...devices['Desktop Safari'] },
- },
- ],
-
- webServer: {
- command: 'npm run dev',
- url: 'http://localhost:5173',
- reuseExistingServer: !process.env.CI,
- timeout: 120 * 1000,
- },
-});
diff --git a/pyproject.toml b/pyproject.toml
index dc8e7b1..58760cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,31 +30,20 @@ addopts = [
"--strict-markers",
"--tb=short",
]
+# Keep in sync with tests/api/pytest.ini, which is the config actually used
+# when the suite runs from tests/api (--strict-markers is enabled in both).
markers = [
"unit: Unit tests",
"integration: Integration tests",
"api: API endpoint tests",
"slow: Slow running tests",
+ "performance: Performance tests",
+ "contract: API contract tests",
+ "e2e: End-to-end tests",
]
-[tool.coverage.run]
-source = ["api"]
-omit = [
- "*/tests/*",
- "*/test_*",
- "*/__pycache__/*",
-]
-
-[tool.coverage.report]
-exclude_lines = [
- "pragma: no cover",
- "def __repr__",
- "raise AssertionError",
- "raise NotImplementedError",
- "if __name__ == .__main__.:",
- "if TYPE_CHECKING:",
- "@abstractmethod",
-]
+# Coverage settings live in .coverage-config.ini (a single source of truth,
+# referenced explicitly by the Makefile and scripts/check-coverage.sh).
[tool.flake8]
max-line-length = 120
diff --git a/tests/ANALYTICS_TESTS.md b/tests/ANALYTICS_TESTS.md
deleted file mode 100644
index 0eb7766..0000000
--- a/tests/ANALYTICS_TESTS.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Analytics Tests Summary
-
-This document summarizes the new analytics tests added to improve test coverage.
-
-## New Test Files
-
-### 1. API Tests: `tests/api/test_analytics.py`
-
-Comprehensive tests for all analytics API endpoints:
-
-- **TestAnalyticsCollect**: Tests data collection endpoint
-
- - Authentication requirements
- - Successful collection
- - Collection failures
-
-- **TestAnalyticsReport**: Tests report generation endpoint
-
- - Report retrieval
- - Invalid parameters
- - Missing reports
-
-- **TestAnalyticsTrends**: Tests trends endpoint
-
- - Performance trends
- - Player behavior trends
- - Import error handling
-
-- **TestAnalyticsAnomalies**: Tests anomaly detection
-
- - Anomaly detection
- - No data scenarios
-
-- **TestAnalyticsPredictions**: Tests predictions endpoint
-
- - Resource predictions
- - Confidence scores
-
-- **TestPlayerBehavior**: Tests player behavior analytics
-
- - Behavior analysis
- - Peak hours
-
-- **TestCustomReport**: Tests custom report generation
- - Report generation
- - Missing fields handling
-
-**Coverage**: ~95% of analytics endpoints
-
-### 2. Integration Tests: `tests/integration/test-analytics.sh`
-
-BATS tests for analytics system integration:
-
-- Data collection workflow
-- Report generation
-- Anomaly detection
-- Data retention
-- End-to-end workflow
-
-**Coverage**: Complete analytics workflow
-
-### 3. E2E Tests: `tests/e2e/test-analytics-workflow.sh`
-
-End-to-end tests via API:
-
-- Complete API workflow
-- Data collection
-- Report retrieval
-- All analytics endpoints
-- Full workflow validation
-
-**Coverage**: Complete user journey
-
-### 4. Unit Tests: `tests/unit/test-analytics-collector.sh`
-
-Unit tests for analytics collector script:
-
-- Script execution
-- File creation
-- JSON validation
-- Error handling
-- Docker failure handling
-
-**Coverage**: Script functionality
-
-### 5. Comprehensive API Tests: `tests/api/test_api_comprehensive.py`
-
-Enhanced tests for existing API endpoints:
-
-- **TestServerControlComprehensive**: Functional server control tests
-- **TestBackupComprehensive**: Backup operation tests
-- **TestMetricsComprehensive**: Metrics data retrieval
-- **TestConfigFilesComprehensive**: Config file operations
-- **TestPlayersComprehensive**: Player management
-- **TestWorldsComprehensive**: World management
-- **TestErrorHandlingComprehensive**: Error scenarios
-- **TestQueryParameters**: Query parameter handling
-
-**Coverage**: Functional testing beyond auth checks
-
-## Test Coverage Improvements
-
-### Before
-
-- Analytics: 0% coverage
-- API endpoints: ~40% (mostly auth checks)
-- E2E workflows: ~20% (mostly skipped)
-
-### After
-
-- Analytics: ~95% coverage ✅
-- API endpoints: ~65% (functional tests added)
-- E2E workflows: ~35% (analytics workflow added)
-
-## Running the Tests
-
-### Analytics API Tests
-
-```bash
-pytest tests/api/test_analytics.py -v
-```
-
-### Comprehensive API Tests
-
-```bash
-pytest tests/api/test_api_comprehensive.py -v
-```
-
-### Integration Tests
-
-```bash
-bats tests/integration/test-analytics.sh
-```
-
-### E2E Tests
-
-```bash
-bats tests/e2e/test-analytics-workflow.sh
-```
-
-### Unit Tests
-
-```bash
-bats tests/unit/test-analytics-collector.sh
-```
-
-### All Tests
-
-```bash
-./scripts/run-tests.sh
-```
-
-## Next Steps
-
-### High Priority
-
-1. ✅ Analytics API tests - DONE
-2. ✅ Analytics integration tests - DONE
-3. ✅ Analytics E2E tests - DONE
-4. ⚠️ Analytics processor unit tests (Python) - PENDING
-5. ⚠️ Web UI component tests - PENDING
-
-### Medium Priority
-
-6. Complete E2E workflows for other features
-7. More script unit tests
-8. Performance tests
-
-### Low Priority
-
-9. Load tests
-10. Security tests
-11. Compatibility tests
-
-## Test Statistics
-
-- **New Test Files**: 5
-- **New Test Cases**: ~50+
-- **Coverage Increase**: ~15-20%
-- **Analytics Coverage**: 0% → 95%
-
-## Notes
-
-- Most E2E tests are marked as `skip` and require running server
-- Integration tests require Docker and server setup
-- Unit tests can run independently
-- API tests use mocks and can run without server
diff --git a/tests/COMPLETE_TEST_SUMMARY.md b/tests/COMPLETE_TEST_SUMMARY.md
deleted file mode 100644
index 4c5425f..0000000
--- a/tests/COMPLETE_TEST_SUMMARY.md
+++ /dev/null
@@ -1,325 +0,0 @@
-# Complete Test Implementation Summary
-
-This document summarizes all tests implemented to improve coverage across the entire project.
-
-## ✅ All Optional Next Steps Completed
-
-### 1. Analytics Processor Unit Tests ✅
-
-**File**: `tests/api/test_analytics_processor.py`
-
-**Coverage**:
-
-- Data loading functionality (empty files, filtering, invalid JSON)
-- Trend calculation (increasing, decreasing, stable trends)
-- Anomaly detection (Z-score algorithm, severity levels)
-- Predictions (linear prediction, confidence scoring)
-- Player behavior analysis (unique players, peak hours, hourly distribution)
-- Report generation (structure, warnings, recommendations)
-- Performance trends analysis
-
-**Test Cases**: 30+ comprehensive unit tests
-
-### 2. Component Tests for Backups, Players, Worlds ✅
-
-**Files**:
-
-- `web/src/pages/__tests__/Backups.test.jsx` - 12+ tests
-- `web/src/pages/__tests__/Players.test.jsx` - 8+ tests
-- `web/src/pages/__tests__/Worlds.test.jsx` - 6+ tests
-
-**Coverage**:
-
-- Component rendering
-- Loading states
-- Data display
-- User interactions
-- Error handling
-- Empty states
-- API integration
-
-### 3. Visual Regression Tests ✅
-
-**File**: `tests/e2e/browser/visual-regression.spec.js`
-
-**Coverage**:
-
-- Dashboard visual snapshot
-- Analytics page visual snapshot
-- Backups page visual snapshot
-- Players page visual snapshot
-- Worlds page visual snapshot
-- Login page visual snapshot
-
-**Framework**: Playwright with screenshot comparison
-
-### 4. Accessibility Tests ✅
-
-**File**: `web/src/test/a11y.test.jsx`
-
-**Coverage**:
-
-- Analytics page accessibility (WCAG compliance)
-- Dashboard page accessibility
-- Backups page accessibility
-- Players page accessibility
-- Worlds page accessibility
-- Login page accessibility
-- Form label validation
-
-**Framework**: jest-axe
-
-### 5. Browser Automation with Playwright ✅
-
-**Files**:
-
-- `playwright.config.js` - Playwright configuration
-- `tests/e2e/browser/analytics.spec.js` - Analytics browser tests
-- `tests/e2e/browser/user-journey.spec.js` - User journey browser tests
-- `tests/e2e/browser/visual-regression.spec.js` - Visual regression tests
-- `.github/workflows/playwright.yml` - CI/CD integration
-
-**Coverage**:
-
-- Real browser testing (Chromium, Firefox, WebKit)
-- Complete user workflows
-- Visual regression testing
-- Cross-browser compatibility
-
-## Test Statistics
-
-### Total Test Files Created/Updated
-
-- **New Test Files**: 15+
-- **Updated Test Files**: 5+
-- **Total Test Cases**: 250+
-
-### Breakdown by Type
-
-- **API Tests**: 80+ test cases
-- **Component Tests**: 60+ test cases
-- **Integration Tests**: 25+ test cases
-- **E2E Tests**: 40+ test cases
-- **Unit Tests (Scripts)**: 20+ test cases
-- **Accessibility Tests**: 7+ test cases
-- **Visual Tests**: 6+ test cases
-- **Browser Tests**: 15+ test cases
-
-## Coverage Improvements
-
-### Before All Additions
-
-- **Overall Coverage**: ~51%
-- **API Coverage**: ~40%
-- **Component Coverage**: ~20%
-- **E2E Coverage**: ~15%
-- **Analytics Coverage**: 0%
-
-### After All Additions
-
-- **Overall Coverage**: ~70%+ ✅
-- **API Coverage**: ~75%+ ✅
-- **Component Coverage**: ~70%+ ✅
-- **E2E Coverage**: ~55%+ ✅
-- **Analytics Coverage**: ~95%+ ✅
-
-## New Test Files
-
-### Analytics Tests
-
-1. ✅ `tests/api/test_analytics.py` - API endpoint tests
-2. ✅ `tests/api/test_analytics_processor.py` - Algorithm unit tests
-3. ✅ `web/src/pages/__tests__/Analytics.test.jsx` - Component tests
-4. ✅ `web/src/test/integration/analytics.integration.test.jsx` - Integration tests
-5. ✅ `tests/integration/test-analytics.sh` - System integration
-6. ✅ `tests/e2e/test-analytics-workflow.sh` - E2E workflow
-7. ✅ `tests/unit/test-analytics-collector.sh` - Collector unit tests
-8. ✅ `tests/e2e/browser/analytics.spec.js` - Browser tests
-
-### Component Tests
-
-9. ✅ `web/src/pages/__tests__/Backups.test.jsx` - Backups component
-10. ✅ `web/src/pages/__tests__/Players.test.jsx` - Players component
-11. ✅ `web/src/pages/__tests__/Worlds.test.jsx` - Worlds component
-
-### E2E Tests
-
-12. ✅ `tests/e2e/test-complete-user-journey.sh` - Complete journey
-13. ✅ `tests/e2e/test-web-ui-workflow.sh` - Web UI workflow
-14. ✅ `tests/e2e/browser/user-journey.spec.js` - Browser journey
-
-### Accessibility & Visual
-
-15. ✅ `web/src/test/a11y.test.jsx` - Accessibility tests
-16. ✅ `tests/e2e/browser/visual-regression.spec.js` - Visual tests
-
-### Comprehensive API Tests
-
-17. ✅ `tests/api/test_api_comprehensive.py` - Functional API tests
-
-## Running All Tests
-
-### Complete Test Suite
-
-```bash
-# All tests
-make test
-
-# Specific test types
-make test-api # API tests only
-make test-web # Web UI tests only
-make test-web-a11y # Accessibility tests
-make test-playwright # Browser tests
-make test-e2e # E2E tests
-```
-
-### Individual Test Suites
-
-```bash
-# Python tests
-pytest tests/api/ -v
-
-# Component tests
-cd web && npm test
-
-# Browser tests
-cd web && npm run test:playwright
-
-# Accessibility
-cd web && npm run test:a11y
-
-# Visual regression
-cd web && npx playwright test tests/e2e/browser/visual-regression.spec.js
-```
-
-## Test Configuration
-
-### Playwright
-
-- **Config**: `playwright.config.js`
-- **Browsers**: Chromium, Firefox, WebKit
-- **Screenshots**: On failure
-- **Traces**: On first retry
-
-### Vitest
-
-- **Config**: `web/vitest.config.js`
-- **Environment**: jsdom
-- **Coverage**: v8 provider
-- **Setup**: Includes jest-axe matchers
-
-### Pytest
-
-- **Config**: `tests/api/pytest.ini`
-- **Coverage**: pytest-cov
-- **Markers**: unit, integration, api, slow
-
-## CI/CD Integration
-
-### GitHub Actions Workflows
-
-- ✅ `.github/workflows/tests.yml` - Main test workflow
-- ✅ `.github/workflows/coverage.yml` - Coverage reporting
-- ✅ `.github/workflows/playwright.yml` - Browser tests (NEW)
-
-### Test Execution
-
-- Runs on all pull requests
-- Runs on pushes to main
-- Generates coverage reports
-- Publishes test results
-- Screenshots on failure
-
-## Documentation
-
-### New Documentation Files
-
-1. ✅ `docs/TESTING_COMPLETE.md` - Complete testing guide
-2. ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide
-3. ✅ `docs/TEST_COVERAGE.md` - Coverage guide
-4. ✅ `tests/ANALYTICS_TESTS.md` - Analytics tests summary
-5. ✅ `tests/TEST_SUMMARY.md` - Test summary
-6. ✅ `tests/COMPLETE_TEST_SUMMARY.md` - This document
-7. ✅ `tests/e2e/browser/README.md` - Browser tests guide
-
-## Test Quality Metrics
-
-### Coverage Goals
-
-- ✅ **Overall**: 70%+ (target: 70%) - ACHIEVED
-- ✅ **API**: 75%+ (target: 75%) - ACHIEVED
-- ✅ **Components**: 70%+ (target: 70%) - ACHIEVED
-- ✅ **E2E**: 55%+ (target: 50%) - EXCEEDED
-- ✅ **Analytics**: 95%+ (target: 80%) - EXCEEDED
-
-### Test Execution
-
-- **Unit Tests**: < 5 seconds
-- **Component Tests**: < 10 seconds
-- **Integration Tests**: < 15 seconds
-- **E2E Tests**: < 30 seconds (when not skipped)
-- **Browser Tests**: < 60 seconds
-
-### Test Reliability
-
-- **Flaky Tests**: 0
-- **Skipped Tests**: E2E tests (require running server)
-- **Failing Tests**: 0
-
-## Key Achievements
-
-### ✅ Complete Test Coverage
-
-- All major features have comprehensive tests
-- Analytics system fully tested
-- Web UI components tested
-- E2E workflows validated
-
-### ✅ Quality Assurance
-
-- Accessibility compliance (WCAG)
-- Visual regression prevention
-- Cross-browser compatibility
-- Error handling validation
-
-### ✅ Developer Experience
-
-- Easy test execution
-- Clear test organization
-- Comprehensive documentation
-- CI/CD integration
-
-## Next Steps (Future Enhancements)
-
-### Performance Testing
-
-- Load testing
-- Stress testing
-- Performance benchmarks
-
-### Security Testing
-
-- Penetration testing
-- Security vulnerability scanning
-- OWASP compliance
-
-### Advanced Testing
-
-- Mutation testing
-- Property-based testing
-- Contract testing
-
-## See Also
-
-- [Testing Guide](README.md)
-- [Complete Testing Guide](../docs/TESTING_COMPLETE.md)
-- [Web UI Testing Guide](../docs/WEB_UI_TESTING.md)
-- [Test Coverage Guide](../docs/TEST_COVERAGE.md)
-- [Analytics Tests](ANALYTICS_TESTS.md)
-
----
-
-**Status**: ✅ All optional next steps completed!
-**Coverage**: ~70%+ overall (exceeds 60% target)
-**Test Cases**: 250+ comprehensive tests
-**Last Updated**: 2025-01-27
diff --git a/tests/README.md b/tests/README.md
index b66d0fa..f09835b 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,189 +1,50 @@
-# Testing Guide
+# Tests
-This directory contains automated tests for the Minecraft Server project.
+The full testing guide lives in [docs/TESTING.md](../docs/TESTING.md); web-specific
+details are in [docs/WEB_UI_TESTING.md](../docs/WEB_UI_TESTING.md). This file just
+maps the directory.
-## Test Structure
+## Layout
```
tests/
-├── unit/ # Unit tests for individual scripts
-├── integration/ # Integration tests
-├── api/ # API endpoint tests
-├── e2e/ # End-to-end tests for complete workflows
-├── helpers/ # Test utilities and helpers
-│ ├── test-utils.sh # Common test functions
-│ ├── mock-server.sh # Mock server for testing
-│ ├── bats-support/ # BATS support library
-│ └── bats-assert/ # BATS assertion library
-└── fixtures/ # Test data and fixtures
+├── api/ pytest suite for the Flask API — run from THIS directory
+│ (tests/api/pytest.ini holds the coverage flags and markers)
+├── unit/ BATS unit tests for individual shell scripts
+├── integration/ BATS integration tests across scripts
+├── e2e/ BATS end-to-end workflows (need a running server)
+└── helpers/ Shared test utilities, mock server, BATS support libraries
```
-## Running Tests
+Playwright browser tests live in [`web/tests/e2e/`](../web/tests/e2e/), and React
+unit tests sit beside their components in `web/src/**/__tests__/`.
-### Run All Tests
+## Running
```bash
-./scripts/run-tests.sh
+make test # syntax checks + pytest + vitest
+make test-api # pytest only
+make test-web # vitest only
+make test-playwright # Playwright browser tests
+make test-e2e # BATS end-to-end
+make coverage # pytest with a coverage report
```
-### Run Specific Test Suite
+Or directly:
```bash
-# Unit tests only
-./scripts/run-tests.sh unit
-
-# Integration tests only
-./scripts/run-tests.sh integration
-
-# API tests only
-./scripts/run-tests.sh api
-
-# E2E tests only
-./scripts/run-tests.sh e2e
-```
-
-### Run Individual Test
-
-```bash
-# Bash test
-bash tests/unit/test-manage.sh
-
-# Python test
-python3 -m pytest tests/api/test_api.py
-```
-
-## Test Requirements
-
-### Bash Tests
-
-- `bats` (Bash Automated Testing System) - for bash script tests
-- Standard bash utilities
-
-### Python Tests
-
-- `pytest` - Python testing framework
-- `requests` - For API testing
-
-Install dependencies:
-
-```bash
-./scripts/run-tests.sh install-deps
-```
-
-## Writing Tests
-
-### Bash Script Tests
-
-Create test file: `tests/unit/test-.sh`
-
-```bash
-#!/usr/bin/env bats
-
-load 'helpers/bats-support/load'
-load 'helpers/bats-assert/load'
-
-@test "script does something" {
- run ./scripts/script.sh command
- assert_success
- assert_output --partial "expected output"
-}
-```
-
-### End-to-End Tests
-
-Create E2E test file: `tests/e2e/test-.sh`
-
-```bash
-#!/usr/bin/env bats
-
-load 'helpers/bats-support/load'
-load 'helpers/bats-assert/load'
-load 'helpers/test-utils.sh'
-
-@test "complete workflow test" {
- # Test complete workflow
- run some_command
- assert_success
-}
-```
-
-### Python Tests
-
-Create test file: `tests/api/test_.py`
-
-```python
-import pytest
-from api.server import app
-
-def test_endpoint(client):
- response = client.get('/api/health')
- assert response.status_code == 200
-```
-
-## Test Utilities
-
-### test-utils.sh
-
-Common test functions:
-
-- `create_test_dir()` - Create temporary test directory
-- `wait_for_server()` - Wait for server to be ready
-- `create_test_backup()` - Create test backup file
-- `api_request()` - Make authenticated API request
-- `assert_file_exists()` - Assert file exists
-- `assert_file_contains()` - Assert file contains text
-
-### mock-server.sh
-
-Mock Minecraft server for testing:
-
-- `start_mock_server` - Start mock server
-- `stop_mock_server` - Stop mock server
-- `status_mock_server` - Check server status
-
-Usage:
-
-```bash
-source tests/helpers/mock-server.sh
-start_mock_server
-# Run tests
-stop_mock_server
-```
-
-## CI/CD Integration
-
-Tests run automatically on:
-
-- Pull requests
-- Pushes to main branch
-- Manual workflow dispatch
-
-See `.github/workflows/tests.yml` for configuration.
-
-## Test Coverage
-
-Run tests with coverage:
-
-```bash
-# Python tests with coverage
-pytest tests/api/ --cov=api --cov-report=html
-
-# View coverage report
-open htmlcov/index.html
-
-# Web UI tests with coverage
-cd web
-npm run test:coverage
-
-# Check coverage threshold
-./scripts/check-coverage.sh check
+./scripts/run-tests.sh [unit|integration|api|e2e]
+cd tests/api && pytest -v
+cd tests/api && pytest -v -m performance # markers: unit, integration, api,
+ # slow, performance, contract, e2e
+bats tests/unit/test-manage.sh
```
-## Current Coverage Status
+## Requirements
-- **API Tests**: ~65% coverage
-- **Web UI Component Tests**: ~50% coverage
-- **E2E Workflows**: ~40% coverage
-- **Overall Coverage**: ~65%+ (target: 70%)
+- `bats` plus `bats-support` / `bats-assert` (vendored in `helpers/`) for shell tests
+- Python dependencies from `api/requirements-test.txt`
+- `cd web && npm install` for Vitest and Playwright
-See [TEST_COVERAGE.md](../docs/TEST_COVERAGE.md) for detailed coverage information.
+`--strict-markers` is enabled, so a new pytest marker must be registered in
+`tests/api/pytest.ini` and `pyproject.toml` before it can be used.
diff --git a/tests/TEST_SUMMARY.md b/tests/TEST_SUMMARY.md
deleted file mode 100644
index f84e898..0000000
--- a/tests/TEST_SUMMARY.md
+++ /dev/null
@@ -1,234 +0,0 @@
-# Test Coverage Summary
-
-This document summarizes all tests added to improve coverage, including web UI component tests and E2E workflows.
-
-## New Tests Added
-
-### 1. Analytics Component Tests ✅
-
-**File**: `web/src/pages/__tests__/Analytics.test.jsx`
-
-**Coverage**:
-
-- Component rendering (title, loading states)
-- Tab navigation (overview, performance, players, anomalies, predictions)
-- Time period selection
-- Data collection button
-- Report generation button
-- Warnings and recommendations display
-- Error handling
-- Periodic data updates
-
-**Test Cases**: 15+ comprehensive tests
-
-### 2. Analytics Integration Tests ✅
-
-**File**: `web/src/test/integration/analytics.integration.test.jsx`
-
-**Coverage**:
-
-- Complete data loading workflow
-- Multi-step user interactions
-- Tab navigation workflow
-- Period change and refresh
-- Anomaly detection display
-
-**Test Cases**: 4 integration scenarios
-
-### 3. Complete User Journey E2E Tests ✅
-
-**File**: `tests/e2e/test-complete-user-journey.sh`
-
-**Coverage**:
-
-- Registration → Login → Dashboard → Analytics
-- Server management workflow
-- Backup management workflow
-- Analytics → Report → Action workflow
-- Configuration management
-- World management
-- Error handling scenarios
-
-**Test Cases**: 9 complete workflows
-
-### 4. Web UI Workflow E2E Tests ✅
-
-**File**: `tests/e2e/test-web-ui-workflow.sh`
-
-**Coverage**:
-
-- Login page access
-- Registration workflow
-- Dashboard data loading
-- Analytics navigation workflow
-- Backup management via API
-- Player management via API
-- Error handling
-- Session management
-
-**Test Cases**: 8 UI workflow scenarios
-
-### 5. Analytics API Tests ✅
-
-**File**: `tests/api/test_analytics.py` (Previously created)
-
-**Coverage**: All analytics endpoints with comprehensive test cases
-
-### 6. Comprehensive API Tests ✅
-
-**File**: `tests/api/test_api_comprehensive.py` (Previously created)
-
-**Coverage**: Functional tests beyond authentication
-
-## Test Coverage Improvements
-
-### Before
-
-- **Web UI Component Tests**: ~20% (only basic components)
-- **E2E Workflows**: ~15% (mostly skipped/placeholder)
-- **Analytics Tests**: 0%
-- **Overall Coverage**: ~51%
-
-### After
-
-- **Web UI Component Tests**: ~50% (+30%)
-- **E2E Workflows**: ~40% (+25%)
-- **Analytics Tests**: ~95% (+95%)
-- **Overall Coverage**: ~65%+ (+14%+)
-
-## Test Statistics
-
-### New Test Files
-
-- `web/src/pages/__tests__/Analytics.test.jsx` - 15+ test cases
-- `web/src/test/integration/analytics.integration.test.jsx` - 4 test cases
-- `tests/e2e/test-complete-user-journey.sh` - 9 test cases
-- `tests/e2e/test-web-ui-workflow.sh` - 8 test cases
-
-### Total New Tests
-
-- **Component Tests**: 15+
-- **Integration Tests**: 4
-- **E2E Tests**: 17
-- **Total**: 36+ new test cases
-
-## Running the Tests
-
-### Web UI Tests
-
-```bash
-cd web
-npm test # All tests
-npm test Analytics # Analytics tests only
-npm test integration # Integration tests only
-npm run test:coverage # With coverage
-```
-
-### E2E Tests
-
-```bash
-# Complete user journey
-bats tests/e2e/test-complete-user-journey.sh
-
-# Web UI workflows
-bats tests/e2e/test-web-ui-workflow.sh
-
-# Analytics workflow
-bats tests/e2e/test-analytics-workflow.sh
-```
-
-### All Tests
-
-```bash
-./scripts/run-tests.sh
-```
-
-## Test Coverage by Area
-
-### Analytics System
-
-- ✅ API endpoint tests (95%)
-- ✅ Component tests (90%)
-- ✅ Integration tests (85%)
-- ✅ E2E workflow tests (90%)
-- ✅ Unit tests for scripts (80%)
-
-### Web UI Components
-
-- ✅ Analytics component (90%)
-- ⚠️ Dashboard component (60%)
-- ⚠️ Other components (40%)
-
-### E2E Workflows
-
-- ✅ Complete user journey (80%)
-- ✅ Analytics workflow (85%)
-- ✅ Web UI workflows (75%)
-- ⚠️ Other workflows (30%)
-
-## Next Steps
-
-### High Priority
-
-1. ✅ Analytics component tests - DONE
-2. ✅ Analytics integration tests - DONE
-3. ✅ E2E workflow tests - DONE
-4. ⚠️ Analytics processor unit tests (Python) - PENDING
-5. ⚠️ More component tests (Backups, Players, Worlds pages)
-
-### Medium Priority
-
-6. Visual regression tests
-7. Accessibility tests
-8. Performance tests
-9. Browser automation (Playwright/Cypress)
-
-### Low Priority
-
-10. Visual snapshot tests
-11. Mobile responsive tests
-12. Cross-browser tests
-
-## Test Quality Metrics
-
-### Code Coverage
-
-- **Statements**: 65%+ (target: 70%)
-- **Branches**: 60%+ (target: 65%)
-- **Functions**: 70%+ (target: 75%)
-- **Lines**: 65%+ (target: 70%)
-
-### Test Execution
-
-- **Unit Tests**: < 5 seconds
-- **Integration Tests**: < 10 seconds
-- **E2E Tests**: < 30 seconds (when not skipped)
-
-### Test Reliability
-
-- **Flaky Tests**: 0
-- **Skipped Tests**: E2E tests (require running server)
-- **Failing Tests**: 0
-
-## Documentation
-
-- ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide
-- ✅ `docs/TEST_COVERAGE.md` - Test coverage guide
-- ✅ `tests/ANALYTICS_TESTS.md` - Analytics tests summary
-- ✅ `tests/TEST_SUMMARY.md` - This document
-
-## CI/CD Integration
-
-All new tests are integrated into CI/CD:
-
-- Run on pull requests
-- Run on pushes to main
-- Coverage reports generated
-- Test results published
-
-## See Also
-
-- [Testing Guide](README.md)
-- [Web UI Testing Guide](../docs/WEB_UI_TESTING.md)
-- [Test Coverage Guide](../docs/TEST_COVERAGE.md)
-- [Analytics Tests](ANALYTICS_TESTS.md)
diff --git a/tests/api/pytest.ini b/tests/api/pytest.ini
index 2387fc0..9094b53 100644
--- a/tests/api/pytest.ini
+++ b/tests/api/pytest.ini
@@ -3,11 +3,17 @@ testpaths = .
python_files = test_*.py
python_classes = Test*
python_functions = test_*
+# --cov-config is required: .coverage-config.ini is not one of the filenames
+# coverage.py auto-discovers, and coverage only looks in the current directory,
+# which is tests/api for every documented entry point. Without the flag the
+# exclusions and fail_under are silently skipped. The Makefile and CI pass the
+# same path.
addopts =
-v
--strict-markers
--tb=short
--cov=api
+ --cov-config=../../.coverage-config.ini
--cov-report=term-missing
--cov-report=html:htmlcov
--cov-report=xml:coverage.xml
diff --git a/tests/e2e/browser/README.md b/tests/e2e/browser/README.md
deleted file mode 100644
index 97f0f1e..0000000
--- a/tests/e2e/browser/README.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# Browser E2E Tests
-
-Browser automation tests using Playwright for real browser testing.
-
-## Setup
-
-### Install Dependencies
-
-```bash
-cd web
-npm install
-npx playwright install
-```
-
-### Configuration
-
-- **Config File**: `playwright.config.js`
-- **Browsers**: Chromium, Firefox, WebKit
-- **Base URL**: http://localhost:5173
-
-## Running Tests
-
-### All Browser Tests
-
-```bash
-cd web
-npx playwright test
-```
-
-### Specific Test File
-
-```bash
-cd web
-npx playwright test tests/e2e/analytics.spec.js
-```
-
-**Note**: Test files have been moved from `tests/e2e/browser/` to `web/tests/e2e/` to ensure proper module resolution.
-
-### With UI
-
-```bash
-npx playwright test --ui
-```
-
-### Visual Regression
-
-```bash
-npx playwright test tests/e2e/browser/visual-regression.spec.js
-```
-
-### Update Snapshots
-
-```bash
-npx playwright test --update-snapshots
-```
-
-## Test Files
-
-### analytics.spec.js
-
-Tests for Analytics page:
-
-- Page loading
-- Tab navigation
-- Time period selection
-- Data collection
-- Report generation
-
-### user-journey.spec.js
-
-Complete user journey tests:
-
-- Registration → Login → Dashboard
-- Navigation through all pages
-- Server management
-
-### visual-regression.spec.js
-
-Visual regression tests:
-
-- Dashboard snapshot
-- Analytics page snapshot
-- Backups page snapshot
-- Players page snapshot
-- Worlds page snapshot
-- Login page snapshot
-
-## Writing Tests
-
-### Basic Test Structure
-
-```javascript
-import { test, expect } from '@playwright/test';
-
-test('test description', async ({ page }) => {
- await page.goto('/path');
- await expect(page.getByText('Expected')).toBeVisible();
-});
-```
-
-### Mocking API
-
-```javascript
-await page.route('**/api/endpoint', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({ data: 'value' }),
- });
-});
-```
-
-### Visual Snapshots
-
-```javascript
-await expect(page).toHaveScreenshot('filename.png', {
- fullPage: true,
- maxDiffPixels: 100,
-});
-```
-
-## CI/CD
-
-Browser tests run in CI/CD:
-
-- On pull requests
-- On pushes to main
-- Screenshots on failure
-- HTML reports generated
-
-## See Also
-
-- [Playwright Documentation](https://playwright.dev/)
-- [Testing Guide](../../README.md)
diff --git a/tests/e2e/browser/analytics.spec.js b/tests/e2e/browser/analytics.spec.js
deleted file mode 100644
index 9faa296..0000000
--- a/tests/e2e/browser/analytics.spec.js
+++ /dev/null
@@ -1,150 +0,0 @@
-import { expect, test } from '@playwright/test';
-
-test.describe('Analytics Page', () => {
- test.beforeEach(async ({ page }) => {
- // Mock API responses
- await page.route('**/api/analytics/report*', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- report: {
- generated_at: '2024-01-27T12:00:00',
- period_hours: 24,
- player_behavior: {
- unique_players: 5,
- peak_hour: 20,
- hourly_distribution: { 20: 10, 21: 8 },
- },
- performance: {
- tps: {
- current: 20.0,
- average: 19.8,
- trend: { direction: 'stable' },
- },
- cpu: { current: 50.0 },
- memory: { current: 1000 },
- },
- summary: {
- status: 'healthy',
- warnings: [],
- recommendations: [],
- },
- },
- }),
- });
- });
-
- await page.route('**/api/analytics/trends*', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- trends: {
- tps: { current: 20.0, trend: { direction: 'stable' } },
- cpu: { current: 50.0 },
- memory: { current: 1000 },
- },
- }),
- });
- });
-
- await page.route('**/api/analytics/anomalies*', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({ anomalies: [] }),
- });
- });
-
- await page.route('**/api/analytics/predictions*', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- prediction: { predicted: 1200, confidence: 85.0 },
- }),
- });
- });
-
- await page.route('**/api/analytics/player-behavior*', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- behavior: { unique_players: 5, peak_hour: 20 },
- }),
- });
- });
-
- // Mock authentication
- await page.goto('/analytics');
- await page.evaluate(() => {
- localStorage.setItem('api_key', 'test-api-key');
- });
- });
-
- test('should load analytics dashboard', async ({ page }) => {
- await page.goto('/analytics');
- await expect(page.getByText('Analytics Dashboard')).toBeVisible();
- });
-
- test('should display overview tab by default', async ({ page }) => {
- await page.goto('/analytics');
- await expect(page.getByText('Summary')).toBeVisible();
- await expect(page.getByText('Current TPS')).toBeVisible();
- });
-
- test('should switch to performance tab', async ({ page }) => {
- await page.goto('/analytics');
- await page.click('button:has-text("Performance")');
- await expect(page.getByText('TPS (Ticks Per Second)')).toBeVisible();
- });
-
- test('should switch to players tab', async ({ page }) => {
- await page.goto('/analytics');
- await page.click('button:has-text("Players")');
- await expect(page.getByText('Player Behavior')).toBeVisible();
- });
-
- test('should change time period', async ({ page }) => {
- await page.goto('/analytics');
- await page.selectOption('select', '6');
- await expect(page.getByText('Summary')).toBeVisible();
- });
-
- test('should collect analytics data', async ({ page }) => {
- let collectCalled = false;
- await page.route('**/api/analytics/collect', async route => {
- collectCalled = true;
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({ success: true, message: 'Data collected' }),
- });
- });
-
- await page.goto('/analytics');
- await page.click('button:has-text("Collect Data")');
- await expect(collectCalled).toBeTruthy();
- });
-
- test('should generate custom report', async ({ page }) => {
- let generateCalled = false;
- await page.route('**/api/analytics/custom-report', async route => {
- generateCalled = true;
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- report: {},
- saved_as: 'custom_report.json',
- }),
- });
- });
-
- await page.goto('/analytics');
- await page.click('button:has-text("Generate Report")');
- await expect(generateCalled).toBeTruthy();
- });
-});
diff --git a/tests/e2e/browser/user-journey.spec.js b/tests/e2e/browser/user-journey.spec.js
deleted file mode 100644
index 39a6fcd..0000000
--- a/tests/e2e/browser/user-journey.spec.js
+++ /dev/null
@@ -1,88 +0,0 @@
-import { expect, test } from '@playwright/test';
-
-test.describe('Complete User Journey', () => {
- test('user can register, login, and access dashboard', async ({ page }) => {
- const testUser = `testuser_${Date.now()}`;
- const testPassword = 'TestPassword123!';
-
- // Step 1: Register
- await page.goto('/register');
- await page.fill('input[name="username"]', testUser);
- await page.fill('input[name="password"]', testPassword);
- await page.fill('input[name="confirmPassword"]', testPassword);
- await page.click('button:has-text("Register")');
-
- // Step 2: Login
- await page.goto('/login');
- await page.fill('input[name="username"]', testUser);
- await page.fill('input[name="password"]', testPassword);
- await page.click('button:has-text("Login")');
-
- // Step 3: Access Dashboard
- await page.waitForURL('/dashboard');
- await expect(page.getByText('Dashboard')).toBeVisible();
- });
-
- test('user can navigate through all main pages', async ({ page }) => {
- // Mock authentication
- await page.evaluate(() => {
- localStorage.setItem('api_key', 'test-api-key');
- });
-
- // Mock API responses
- await page.route('**/api/**', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({}),
- });
- });
-
- await page.goto('/dashboard');
- await expect(page.getByText('Dashboard')).toBeVisible();
-
- // Navigate to Analytics
- await page.click('a:has-text("Analytics")');
- await expect(page.getByText('Analytics Dashboard')).toBeVisible();
-
- // Navigate to Players
- await page.click('a:has-text("Players")');
- await expect(page.getByText('Player Management')).toBeVisible();
-
- // Navigate to Backups
- await page.click('a:has-text("Backups")');
- await expect(page.getByText(/backup/i)).toBeVisible();
-
- // Navigate to Worlds
- await page.click('a:has-text("Worlds")');
- await expect(page.getByText('World Management')).toBeVisible();
- });
-
- test('user can manage server from dashboard', async ({ page }) => {
- await page.evaluate(() => {
- localStorage.setItem('api_key', 'test-api-key');
- });
-
- let startCalled = false;
- await page.route('**/api/server/start', async route => {
- startCalled = true;
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({ success: true }),
- });
- });
-
- await page.route('**/api/status', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({ running: false, status: 'Stopped' }),
- });
- });
-
- await page.goto('/dashboard');
- await page.click('button:has-text("Start Server")');
- await expect(startCalled).toBeTruthy();
- });
-});
diff --git a/tests/e2e/browser/visual-regression.spec.js b/tests/e2e/browser/visual-regression.spec.js
deleted file mode 100644
index ec60226..0000000
--- a/tests/e2e/browser/visual-regression.spec.js
+++ /dev/null
@@ -1,79 +0,0 @@
-import { expect, test } from '@playwright/test';
-
-test.describe('Visual Regression Tests', () => {
- test.beforeEach(async ({ page }) => {
- // Mock API responses
- await page.route('**/api/**', async route => {
- await route.fulfill({
- status: 200,
- contentType: 'application/json',
- body: JSON.stringify({
- running: true,
- status: 'Up',
- players: [],
- backups: [],
- worlds: [],
- metrics: {},
- }),
- });
- });
-
- await page.evaluate(() => {
- localStorage.setItem('api_key', 'test-api-key');
- });
- });
-
- test('dashboard visual snapshot', async ({ page }) => {
- await page.goto('/dashboard');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('dashboard.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-
- test('analytics page visual snapshot', async ({ page }) => {
- await page.goto('/analytics');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('analytics.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-
- test('backups page visual snapshot', async ({ page }) => {
- await page.goto('/backups');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('backups.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-
- test('players page visual snapshot', async ({ page }) => {
- await page.goto('/players');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('players.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-
- test('worlds page visual snapshot', async ({ page }) => {
- await page.goto('/worlds');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('worlds.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-
- test('login page visual snapshot', async ({ page }) => {
- await page.goto('/login');
- await page.waitForLoadState('networkidle');
- await expect(page).toHaveScreenshot('login.png', {
- fullPage: true,
- maxDiffPixels: 100,
- });
- });
-});
diff --git a/web/playwright-report/index.html b/web/playwright-report/index.html
deleted file mode 100644
index 72914ee..0000000
--- a/web/playwright-report/index.html
+++ /dev/null
@@ -1,85 +0,0 @@
-
-
-
-
-
-
-
-
- Playwright Test Report
-
-
-
-
-
-
-
-
\ No newline at end of file