docs: add MkDocs documentation site with GitHub Pages deployment

- Add comprehensive docs pages (quick-start, auth, troubleshooting,
  etc.)
- Add GitHub Pages workflow and CI docs build job
- Streamline README by moving detailed content to docs site

Author: lroolle

.github/workflows/ci.yml

@@ -43,3 +43,23 @@ jobs:
         run: |
           chmod +x scripts/version-check.sh
           ./scripts/version-check.sh
+
+  docs:
+    name: Docs Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs-requirements.txt
+
+      - name: Build docs
+        run: mkdocs build --strict

.github/workflows/pages.yml

@@ -0,0 +1,60 @@
+name: Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Docs Site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs-requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Remove unpublished artifacts
+        run: rm -rf site/devlog
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy Docs Site
+    if: github.ref == 'refs/heads/main'
+    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

.gitignore

@@ -150,3 +150,6 @@ claude-yolo-pro/
 
 # Claude YOLO Config Files - Local overrides
 .claude-yolo.local
+
+# MkDocs output
+site/

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to Claude Code YOLO will be documented in this file.
+All notable changes to deva.sh will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -11,16 +11,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `LICENSE` with the standard MIT license text
 - `SECURITY.md` with private vulnerability reporting guidance
 - `CONTRIBUTING.md` with the repo workflow, local checks, and release rules
+- `docs/` guide set for quick start, internals, philosophy, authentication, advanced usage, and troubleshooting
+- `mkdocs.yml`, `docs/index.md`, and GitHub Pages workflow for publishing the docs site
 
 ### Fixed
 - Claude `--auth-with api-key` now forwards `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_BASE_URL`
 - Non-default auth no longer moves live host credential files out of the way; it overlays the default credential path with a safe placeholder instead
 - `--dry-run` no longer mutates config homes through autolink or scaffold writes
+- Copilot `--dry-run` no longer starts the local proxy as a side effect
 - Config-home fan-out skips loose credential files, backup files, VCS junk, and `.DS_Store`
+- Auth-specific persistent containers now include the agent in the name suffix, avoiding cross-agent reuse with the wrong env or mounts
 - `install.sh` now installs the full current agent set, including Gemini and `shared_auth.sh`
 
 ### Changed
-- Rewrote `README.md` into a cleaner OSS landing page with badges, quick start, auth matrix, and security warnings
+- Rewrote `README.md` into a deva.sh front page with a real docs index and sharper OSS positioning
+- CI now builds the MkDocs site so Pages breakage gets caught before merge
 - Updated `workflows/RELEASE.md` to use `deva.sh` as the source of truth for version bumps
 
 ## [0.9.1] - 2026-01-09

CONTRIBUTING.md

@@ -49,7 +49,8 @@ If you change Docker image behavior, auth flows, or release logic, test those pa
 
 Update docs when behavior changes:
 
-- `README.md` for user-facing workflow
+- `README.md` for the front page and project positioning
+- `docs/` for long-form user guides
 - `CHANGELOG.md` for release notes
 - `DEV-LOGS.md` for significant work
 - `SECURITY.md` when the reporting path or threat model changes

DEV-LOGS.md

@@ -13,6 +13,18 @@
 - Minimal markdown markers, no unnecessary formatting, minimal emojis.
 - Reference issue numbers in the format `#<issue-number>` for easy linking.
 
+# [2026-03-11] Dev Log: deva.sh docs spine for OSS release
+- Why: the repo had a decent landing page but still dumped too much context into one README and did not read like an organized OSS project
+- What:
+  - rewrote `README.md` as the deva.sh front page instead of a giant mixed-purpose document
+  - added `docs/index.md`, `docs/quick-start.md`, `docs/how-it-works.md`, `docs/philosophy.md`, `docs/authentication.md`, `docs/advanced-usage.md`, and `docs/troubleshooting.md`
+  - revalidated the docs against real `--dry-run` output instead of just `--help`
+  - corrected the docs and CLI help to describe persistent containers as project-scoped shapes, not a naive single-container story
+  - fixed auth-specific persistent naming to include the agent and fixed Copilot `--dry-run` so it no longer starts the proxy
+  - added MkDocs config, a GitHub Pages deploy workflow, a dedicated docs site home page, and CI docs-build validation
+  - aligned `CHANGELOG.md` and contribution guidance with the new docs split
+- Result: the repo now has an actual docs spine for onboarding, internals, auth, and advanced workflows, the documented behavior matches the observed runtime shape, and the repo is ready to publish docs through GitHub Pages
+
 # [2026-03-11] Dev Log: OSS repo polish and auth mount cleanup
 - Why: the repo still looked half-finished in public, the installer lagged behind the actual agent set, and recent auth switching work exposed ugly mount behavior
 - What: