Migrate project docs to mdBook (#3)

* docs: migrate project docs to mdbook

* ci: enable dependabot updates

Author: rosterloh

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:00"
+      timezone: "Europe/London"
+    open-pull-requests-limit: 5
+    groups:
+      cargo-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:30"
+      timezone: "Europe/London"
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+env:
+  MDBOOK_VERSION: 0.5.2
+
+jobs:
+  build:
+    name: Build mdBook
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install mdBook
+        run: cargo install mdbook --version "${MDBOOK_VERSION}" --locked
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Configure GitHub Pages
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v6
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/book
+
+  deploy:
+    name: Deploy GitHub Pages
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -1 +1,2 @@
 /target
+/docs/book

AGENTS.md

@@ -32,6 +32,12 @@ cargo test -p talos-agent --test integration --features quic  # + QUIC tests
 cd rclrs_ws && pixi run build
 ```
 
+## Default Change Workflow
+
+- Make repository changes on a feature branch, not directly on `main`, unless the user explicitly asks otherwise.
+- After implementing and validating changes, commit them, push the branch, and open a pull request.
+- Keep unrelated local files out of the commit; do not stage generated output such as `docs/book/`.
+
 ## Architecture
 
 ```
@@ -71,9 +77,16 @@ The agent reads `talos-agent.toml` (or path via `--config`). Key sections:
 - `[control]` — optional joint command publishing
 - `[poses.<name>]` — named joint position presets
 
-## OpenSpec Workflow
+## Documentation
+
+The `docs/` mdBook is the canonical project documentation. Keep current behavior, architecture, usage, configuration, design history, and future plans there. `README.md` should stay short and point readers to the book.
 
-The `openspec/` directory tracks architectural specs and change proposals. Use the `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, and `/opsx:explore` skills to manage the spec-driven workflow.
+Build and preview docs with:
+
+```bash
+mdbook build docs
+mdbook serve docs
+```
 
 ## Changelog Discipline
 

CHANGELOG.md

@@ -7,6 +7,22 @@ those entries into the versioned section when a release is created.
 
 ## [Unreleased]
 
+### Added
+
+- Add canonical mdBook documentation under `docs/` with current behavior, design history, and future plans.
+- Add a GitHub Actions workflow to build and publish the mdBook to GitHub Pages.
+- Add Dependabot version updates for Cargo dependencies and GitHub Actions.
+
+### Changed
+
+- Shorten `README.md` to a project overview that links to the mdBook.
+- Replace legacy spec workflow guidance with mdBook documentation guidance.
+- Document the default branch-and-pull-request workflow for repository changes.
+
+### Removed
+
+- Remove the legacy spec source tree after migrating its useful content into the mdBook.
+
 ## [0.1.2] - 2026-04-28
 
 - No notable changes recorded.