docs: add mkdocs, update links, add architecture documentation

Makefile

@@ -0,0 +1,106 @@
+.PHONY: help docs-install docs-serve docs-build docs-deploy docs-clean docs-validate
+.PHONY: docs-docker-build docs-docker-serve docs-docker-build-site docs-docker-clean docs-docker-compose-up docs-docker-compose-down
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo ""
+	@echo "Local commands (require Python/pip):"
+	@echo "  make docs-install    - Install MkDocs dependencies"
+	@echo "  make docs-serve      - Serve documentation locally (http://127.0.0.1:8000)"
+	@echo "  make docs-build      - Build static documentation site"
+	@echo "  make docs-deploy     - Deploy documentation to GitHub Pages"
+	@echo "  make docs-clean      - Clean build artifacts"
+	@echo "  make docs-validate   - Validate MkDocs configuration"
+	@echo ""
+	@echo "Docker commands (no Python installation required):"
+	@echo "  make docs-docker-build        - Build Docker image for MkDocs"
+	@echo "  make docs-docker-serve        - Serve documentation using Docker"
+	@echo "  make docs-docker-build-site   - Build static site in Docker container"
+	@echo "  make docs-docker-clean        - Clean Docker images and containers"
+	@echo "  make docs-docker-compose-up   - Start docs server with docker-compose"
+	@echo "  make docs-docker-compose-down - Stop docs server with docker-compose"
+	@echo ""
+	@echo "Documentation shortcuts:"
+	@echo "  make docs            - Alias for docs-serve"
+	@echo "  make build-docs      - Alias for docs-build"
+	@echo "  make docs-docker     - Alias for docs-docker-serve"
+
+# Install MkDocs and dependencies
+docs-install:
+	@echo "Installing MkDocs dependencies..."
+	cd docs && pip install -r requirements.txt
+
+# Serve documentation locally with auto-reload
+docs-serve:
+	@echo "Starting MkDocs development server..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && mkdocs serve
+
+# Build static documentation site
+docs-build:
+	@echo "Building static documentation site..."
+	cd docs && mkdocs build
+	@echo "Build complete! Output is in the 'docs/site/' directory"
+
+# Deploy documentation to GitHub Pages
+docs-deploy:
+	@echo "Deploying documentation to GitHub Pages..."
+	cd docs && mkdocs gh-deploy
+
+# Clean build artifacts
+docs-clean:
+	@echo "Cleaning MkDocs build artifacts..."
+	rm -rf docs/site/
+	rm -rf docs/.mkdocs_cache/
+	@echo "Clean complete!"
+
+# Validate MkDocs configuration
+docs-validate:
+	@echo "Validating MkDocs configuration..."
+	cd docs && mkdocs build --strict
+	@echo "Configuration is valid!"
+
+# Docker commands
+docs-docker-build:
+	@echo "Building Docker image for MkDocs..."
+	cd docs && docker build -f Dockerfile -t goplt-docs:latest .
+
+docs-docker-serve: docs-docker-build
+	@echo "Starting MkDocs development server in Docker..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && docker run --rm -it \
+		-p 8000:8000 \
+		-v "$$(pwd):/docs:ro" \
+		goplt-docs:latest
+
+docs-docker-build-site: docs-docker-build
+	@echo "Building static documentation site in Docker..."
+	cd docs && docker run --rm \
+		-v "$$(pwd):/docs:ro" \
+		-v "$$(pwd)/site:/docs/site" \
+		goplt-docs:latest mkdocs build
+	@echo "Build complete! Output is in the 'docs/site/' directory"
+
+docs-docker-clean:
+	@echo "Cleaning Docker images and containers..."
+	-docker stop goplt-docs 2>/dev/null || true
+	-docker rm goplt-docs 2>/dev/null || true
+	-docker rmi goplt-docs:latest 2>/dev/null || true
+	@echo "Clean complete!"
+
+docs-docker-compose-up:
+	@echo "Starting MkDocs server with docker-compose..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && docker-compose -f docker-compose.yml up --build
+
+docs-docker-compose-down:
+	@echo "Stopping MkDocs server..."
+	cd docs && docker-compose -f docker-compose.yml down
+
+# Convenience aliases
+docs: docs-serve
+build-docs: docs-build
+clean-docs: docs-clean
+docs-docker: docs-docker-serve
+