docs: add mkdocs, update links, add architecture documentation

docs/MKDOCS_README.md

@@ -0,0 +1,163 @@
+# MkDocs Setup
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) for documentation.
+
+All documentation tooling files are self-contained in the `docs/` directory.
+
+## Prerequisites
+
+You can run MkDocs in two ways:
+
+**Option 1: Local Python Installation**
+- Python 3.8 or higher
+- pip (Python package manager)
+
+**Option 2: Docker (Recommended - No Python installation needed)**
+- Docker and Docker Compose
+
+## Installation
+
+1. Install the required Python packages:
+
+```bash
+cd docs
+pip install -r requirements.txt
+```
+
+Or if you prefer using a virtual environment:
+
+```bash
+cd docs
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Usage
+
+You can use either the Makefile commands from the project root (recommended) or run MkDocs directly from the `docs/` directory.
+
+### Using Makefile (Recommended)
+
+From the project root, use the Makefile commands:
+
+```bash
+# Using Docker (easiest, no Python needed)
+make docs-docker-compose-up
+# or
+make docs-docker
+
+# Using local Python
+make docs-install    # Install dependencies
+make docs-serve      # Serve documentation
+make docs-build    # Build static site
+make docs-deploy    # Deploy to GitHub Pages
+
+# Show all available commands
+make help
+```
+
+The documentation will be available at `http://127.0.0.1:8000` with live reload enabled.
+
+### Using Docker Directly
+
+From the `docs/` directory:
+
+```bash
+cd docs
+
+# Using docker-compose (easiest)
+docker-compose up --build
+
+# Using Docker directly
+docker build -t goplt-docs:latest .
+docker run --rm -it -p 8000:8000 -v "$(pwd):/docs:ro" goplt-docs:latest
+
+# Build static site
+docker run --rm -v "$(pwd):/docs:ro" -v "$(pwd)/site:/docs/site" goplt-docs:latest mkdocs build
+```
+
+### Using MkDocs Directly
+
+From the `docs/` directory:
+
+```bash
+cd docs
+
+# Serve documentation locally with auto-reload
+mkdocs serve
+
+# Build static site
+mkdocs build
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy
+```
+
+## Configuration
+
+The main configuration file is `docs/mkdocs.yml`. Key settings:
+
+- **Site name and metadata**: Configured at the top
+- **Theme**: Material theme with light/dark mode support
+- **Navigation**: Defined in the `nav` section
+- **Plugins**: Search and git revision date plugins enabled
+- **Markdown extensions**: Various extensions for code highlighting, tables, etc.
+- **docs_dir**: Set to "content" - markdown files are in the content/ subdirectory
+
+## Project Structure
+
+```
+goplt/
+├── docs/                    # Documentation directory (self-contained)
+│   ├── mkdocs.yml          # MkDocs configuration
+│   ├── requirements.txt    # Python dependencies
+│   ├── Dockerfile          # Docker image for MkDocs
+│   ├── docker-compose.yml  # Docker Compose configuration
+│   ├── .dockerignore       # Docker ignore patterns
+│   ├── MKDOCS_README.md    # This file
+│   ├── content/           # Documentation content (markdown files)
+│   │   ├── index.md       # Home page
+│   │   ├── requirements.md # Requirements document
+│   │   ├── plan.md        # Implementation plan
+│   │   ├── playbook.md    # Implementation playbook
+│   │   ├── adr/           # Architecture Decision Records
+│   │   └── stories/       # Implementation tasks
+│   └── site/              # Generated site (gitignored)
+└── Makefile               # Makefile with docs commands (runs from root)
+```
+
+## Adding New Documentation
+
+1. Add markdown files to the `docs/content/` directory
+2. Update `docs/mkdocs.yml` to add entries to the `nav` section
+3. Run `make docs-serve` or `make docs-docker` from project root to preview changes
+
+## Customization
+
+### Theme Colors
+
+Edit the `theme.palette` section in `docs/mkdocs.yml` to change colors.
+
+### Navigation
+
+Update the `nav` section in `docs/mkdocs.yml` to reorganize or add new pages.
+
+### Plugins
+
+Add or remove plugins in the `plugins` section of `docs/mkdocs.yml`.
+
+## Troubleshooting
+
+- **Import errors**: Make sure all dependencies are installed: `cd docs && pip install -r requirements.txt`
+- **Navigation issues**: Check that file paths in `docs/mkdocs.yml` match actual file locations
+- **Build errors**: Run `mkdocs build --verbose` from the `docs/` directory for detailed error messages
+- **Docker issues**: Make sure Docker is running and you have permissions to run containers
+
+## Benefits of Self-Contained Docs
+
+- All documentation tooling is in one place
+- Easy to share or move the docs directory
+- Doesn't pollute the project root
+- Can be versioned or deployed independently
+