docs: add comprehensive documentation with MkDocs (#2)

- Add MkDocs Material theme configuration
- Create documentation structure (Guides, API, Examples, Advanced)
- Write Getting Started guide with complete tutorial
- Write Core Concepts guide explaining architecture
- Document Agent API with complete reference
- Add GitHub Actions workflow for auto-deployment
- Create stubs for remaining documentation pages

Closes #1

Co-authored-by: arcaela <community@arcaelas.com>

Author: arcaela

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+
+      - name: Install MkDocs and dependencies
+        run: |
+          pip install --upgrade pip
+          pip install mkdocs-material
+          pip install mkdocs-minify-plugin
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## \[1.0.4] - 2025-07-17
+
+### Added
+
+- Full integration of the agent’s name and description into the system message.
+
+### Improved
+
+- Enhanced rule and limit handling during conversation flow.
+- Optimized validation process for provider responses.
+
+## \[1.0.3] - 2025-07-17
+
+### Changed
+
+- Renamed the `Bot` class to `Agent` to ensure consistent terminology.
+- Refactored related interfaces to adopt the "Agent" term.
+
+### Documentation
+
+- Updated usage examples and improved main method documentation.
+
+## \[1.0.2] - 2025-07-17
+
+### Added
+
+- Extra integrity checks prior to publishing.
+
+### Fixed
+
+- Minor type issues in core interfaces.
+
+### Changed
+
+- Publication workflow now auto-increments patch version.
+
+## \[1.0.1] - 2025-07-17
+
+### Changed
+
+- Downgraded package version to `1.0.1` to comply with semantic versioning.
+- Simplified internal logic for error handling in tool calls.
+
+### Improved
+
+- Better compatibility with various OpenAI API versions.
+
+## \[2.0.5] _(reverted to 1.0.1)_ - 2025-07-17
+
+### Changed
+
+- Updated package metadata and dependencies.
+- Fixed version numbering to restore correct semantic structure.
+
+### Improved
+
+- Optimized project metadata structure.
+
+## \[1.0.0] - 2025-07-17
+
+### Added
+
+- `yarn.lock` file to ensure dependency consistency.
+- Strict version control enforcement for cross-environment compatibility.
+
+### Documentation
+
+- Improved installation and usage instructions.
+
+## \[0.9.0] - 2025-07-17
+
+### Added
+
+- Initial TypeScript compiler configuration with strict mode.
+- Module aliasing for improved project structure.
+- Optimized compilation options for maximum compatibility.

docs/advanced/architecture.md

@@ -0,0 +1,3 @@
+# architecture.md
+
+Documentation coming soon. Check back later or contribute at [GitHub](https://github.com/arcaelas/agent).

docs/advanced/migration.md

@@ -0,0 +1,3 @@
+# migration.md
+
+Documentation coming soon. Check back later or contribute at [GitHub](https://github.com/arcaelas/agent).

docs/advanced/performance.md

@@ -0,0 +1,3 @@
+# performance.md
+
+Documentation coming soon. Check back later or contribute at [GitHub](https://github.com/arcaelas/agent).

docs/advanced/troubleshooting.md

@@ -0,0 +1,3 @@
+# troubleshooting.md
+
+Documentation coming soon. Check back later or contribute at [GitHub](https://github.com/arcaelas/agent).