feat: add initial documentation and configuration for Brix CLI

[pgoell]

• Introduced mkdocs configuration for project documentation.
• Added comprehensive user guides covering installation, quick start, command usage, and profile management.
• Implemented a GitHub Actions workflow for automatic documentation deployment.
• Created API and developer guides to assist contributors and users in understanding the project structure and contribution process.
• Enhanced README with project description, features, and installation instructions.

[pgoell]

/review

[claude]

Pull Request Review: Documentation Infrastructure

Summary

This PR adds a comprehensive documentation infrastructure for the Brix CLI project using MkDocs with Material theme. The documentation includes user guides, developer guides, and API references, along with automated deployment via GitHub Actions.

---

✅ Strengths

1. Comprehensive Documentation Structure

• Well-organized navigation hierarchy (Getting Started → User Guide → Developer Guide → API)
• Covers all essential aspects: installation, usage, architecture, and contribution guidelines
• API reference setup using mkdocstrings for auto-generated docs from docstrings

2. Professional Setup

• Material theme with dark/light mode support
• Proper mkdocs configuration with useful plugins (search, mkdocstrings, syntax highlighting)
• GitHub Actions workflow for automated deployment to GitHub Pages

3. Developer Experience

• Added convenient poe tasks: docs-serve, docs-build, docs-deploy
• Documentation dependencies properly isolated in optional dependency group
• Clear contribution guidelines and development workflows

4. Alignment with Project Standards

• Follows Google-style docstrings as specified in CLAUDE.md
• Documentation structure aligns with the project's architecture (commands vs modules separation)

---

⚠️ Issues & Recommendations

High Priority Issues

1. Missing Python Version in Workflow

The workflow runs uv python install without specifying a version, which could lead to inconsistent builds.

Recommended:

- name: Set up Python
  run: uv python install 3.10

2. API Documentation Requires Package Installation

The API reference uses mkdocstrings which requires the brix package to be importable during build. The workflow needs to install the package:

- name: Install dependencies
  run: |
    uv sync --extra docs
    uv pip install -e .

Medium Priority Issues

3. Unused mkdocs Plugins

Several plugins are listed in pyproject.toml but not configured in mkdocs.yml:

• mkdocs-gen-files
• mkdocs-literate-nav
• mkdocs-section-index

Recommendation: Either use these plugins or remove them from dependencies.

4. Documentation Build in CI

Consider adding a documentation build check to the CI pipeline for PRs (not just on main branch) by running mkdocs build --strict.

---

🎯 Performance Considerations

The docs workflow could benefit from caching for faster builds.

---

✅ Action Items Checklist

• HIGH: Specify Python version 3.10 in GitHub Actions workflow
• HIGH: Install package during docs build for mkdocstrings
• MEDIUM: Remove unused mkdocs plugins or configure them
• MEDIUM: Add docs build check to PR CI workflow
• LOW: Add workflow caching for faster builds

---

🎉 Conclusion

This is an excellent addition to the project that significantly improves its accessibility and maintainability.

Recommendation: Approve with requested changes

The high-priority issues (Python version specification and package installation for mkdocstrings) should be addressed to ensure the documentation builds successfully on first deployment.

Documentation Content Quality: The user guides, developer guides, and API reference structure are all excellent. Special kudos for the comprehensive "Adding Adapters" guide and architecture documentation.

---

Great work on this comprehensive documentation setup! 🚀