docs: add mdBook guide site and Pages deploy workflow (#15)

* docs(book): add mdBook guide scaffold and chapters

* fix(book): correct mdBook summary external link handling

* ci(docs): add mdBook build and pages deploy workflow

* docs(readme): document mdBook guide site and paths

* chore(gitignore): ignore mdbook output directory

* ci(docs): split mdbook build and deploy permissions

.github/workflows/mdbook.yml

@@ -0,0 +1,56 @@
+name: docs-mdbook
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mdbook-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: latest
+
+      - name: Build book
+        run: mdbook build docs/book
+
+      - name: Upload book artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: mdbook-site
+          path: ./book
+          if-no-files-found: error
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download book artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: mdbook-site
+          path: ./book
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book

.gitignore

@@ -23,3 +23,4 @@ target
 prompts/
 
 *.DS_Store
+book/

README.md

@@ -15,6 +15,15 @@ Alpha. `v0.3.0` released.
 - Real-world user testing: still limited.
 - Issues and PRs welcome.
 
+## Guide Site (mdBook)
+
+Book-style guide source lives under `docs/book/` and is deployed via GitHub Pages:
+
+- Source: `docs/book/src/`
+- Build config: `docs/book/book.toml`
+- CI workflow: `.github/workflows/mdbook.yml`
+- Published URL: `https://milind220.github.io/kicad-ipc-rs/`
+
 ## Usage
 
 ### Async API (Default)

docs/book/book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["Milind Sharma"]
+language = "en"
+src = "src"
+title = "KiCad IPC RS"
+
+[build]
+build-dir = "../../book"
+
+[output.html]
+default-theme = "light"
+git-repository-url = "https://github.com/Milind220/kicad-ipc-rs"
+site-url = "/kicad-ipc-rs/"

docs/book/src/SUMMARY.md

@@ -0,0 +1,8 @@
+# KiCad IPC RS
+
+- [Introduction](intro.md)
+- [Quickstart](quickstart.md)
+- [Usage Patterns](usage-patterns.md)
+- [Examples](examples.md)
+- [Validation and Testing](validation.md)
+- [API Reference](api-reference.md)

docs/book/src/api-reference.md

@@ -0,0 +1,12 @@
+# API Reference
+
+Primary API docs live on docs.rs:
+
+- [kicad-ipc-rs API Reference](https://docs.rs/kicad-ipc-rs)
+
+Key items:
+
+- `KiCadClient` (async)
+- `KiCadClientBlocking` (`blocking` feature)
+- `KiCadError`
+- Typed models under `model::*`

docs/book/src/examples.md

@@ -0,0 +1,40 @@
+# Examples
+
+## Quick Version Probe (Async)
+
+```rust,no_run
+use kicad_ipc_rs::KiCadClient;
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
+    let client = KiCadClient::connect().await?;
+    let version = client.get_version().await?;
+    println!("{:?}", version);
+    Ok(())
+}
+```
+
+## Open Board Detection (Blocking)
+
+```rust,no_run
+use kicad_ipc_rs::KiCadClientBlocking;
+
+fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
+    let client = KiCadClientBlocking::connect()?;
+    let has_board = client.has_open_board()?;
+    println!("open board: {}", has_board);
+    Ok(())
+}
+```
+
+## CLI-first Smoke Testing
+
+Runbook commands:
+
+```bash
+cargo run --features blocking --bin kicad-ipc-cli -- ping
+cargo run --features blocking --bin kicad-ipc-cli -- version
+cargo run --features blocking --bin kicad-ipc-cli -- board-open
+```
+
+Full command catalog: [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)

docs/book/src/intro.md

@@ -0,0 +1,28 @@
+# Introduction
+
+`kicad-ipc-rs` is an async-first Rust client for KiCad IPC.
+
+Project goals:
+
+- Rust-native API for KiCad IPC commands.
+- Typed models for common board/editor operations.
+- Blocking wrapper parity via `feature = "blocking"`.
+- Maintainer-friendly release and proto-regeneration flow.
+
+Current scope:
+
+- KiCad API proto snapshot pinned in repo (`src/proto/generated/`).
+- 56/56 wrapped command families from the current snapshot.
+- Runtime compatibility verified against KiCad `10.0.0-rc1`.
+
+Core entrypoints:
+
+- Async: `kicad_ipc_rs::KiCadClient`
+- Blocking: `kicad_ipc_rs::KiCadClientBlocking` (`blocking` feature)
+- Error type: `kicad_ipc_rs::KiCadError`
+
+Related docs:
+
+- Crate README: [README.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/README.md)
+- CLI runbook: [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)
+- API docs: [docs.rs/kicad-ipc-rs](https://docs.rs/kicad-ipc-rs)

docs/book/src/quickstart.md

@@ -0,0 +1,70 @@
+# Quickstart
+
+## Prereqs
+
+1. KiCad running on the same machine.
+2. IPC socket available (default discovery, or `KICAD_API_SOCKET`).
+3. Optional auth token in `KICAD_API_TOKEN` if your setup requires it.
+
+## Async API (default)
+
+`Cargo.toml`:
+
+```toml
+[dependencies]
+kicad-ipc-rs = "0.3.1"
+tokio = { version = "1", features = ["macros", "rt"] }
+```
+
+```rust,no_run
+use kicad_ipc_rs::KiCadClient;
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
+    let client = KiCadClient::builder()
+        .client_name("quickstart-async")
+        .connect()
+        .await?;
+
+    client.ping().await?;
+    let version = client.get_version().await?;
+    println!("KiCad: {}", version.full_version);
+    Ok(())
+}
+```
+
+## Blocking API
+
+`Cargo.toml`:
+
+```toml
+[dependencies]
+kicad-ipc-rs = { version = "0.3.1", features = ["blocking"] }
+```
+
+```rust,no_run
+use kicad_ipc_rs::KiCadClientBlocking;
+
+fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
+    let client = KiCadClientBlocking::builder()
+        .client_name("quickstart-blocking")
+        .connect()?;
+
+    client.ping()?;
+    let version = client.get_version()?;
+    println!("KiCad: {}", version.full_version);
+    Ok(())
+}
+```
+
+## Environment Variables
+
+| Variable | Purpose | Used by |
+| --- | --- | --- |
+| `KICAD_API_SOCKET` | Explicit IPC socket URI/path override | async + blocking |
+| `KICAD_API_TOKEN` | IPC auth token | async + blocking |
+
+## Next Steps
+
+- Use [`kicad-ipc-cli`](https://github.com/Milind220/kicad-ipc-rs/blob/main/test-scripts/kicad-ipc-cli.rs) for rapid command checks.
+- Follow [Validation and Testing](validation.md) before CI/release.

docs/book/src/usage-patterns.md

@@ -0,0 +1,63 @@
+# Usage Patterns
+
+This chapter targets repeatable integration patterns for tool builders and code generators.
+
+## Pattern: Cheap Health Check
+
+Use at process startup to validate socket + auth + server liveness.
+
+```rust,no_run
+use kicad_ipc_rs::KiCadClient;
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
+    let client = KiCadClient::connect().await?;
+    client.ping().await?;
+    Ok(())
+}
+```
+
+## Pattern: Read-only Query Pipeline
+
+Recommended order for board-aware reads:
+
+1. `get_open_documents()`
+2. `get_nets()`
+3. `get_items_by_net(...)` or `get_items_by_type_codes(...)`
+
+Reason: fail fast on document state before expensive item traversal.
+
+## Pattern: Safe Write Session
+
+Use begin/end commit around mutating commands.
+
+1. `begin_commit(...)`
+2. `create_items(...)` / `update_items(...)` / `delete_items(...)`
+3. `end_commit(..., CommitAction::Commit, ...)`
+
+If errors mid-flight: close with `CommitAction::Abort`/`Drop` per flow.
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Avoidance |
+| --- | --- | --- |
+| Assume KiCad always running | connect errors at startup | explicit prereq check + `ping()` |
+| Skip open-document check | downstream command failures | call `get_open_documents()` first |
+| Mix sync + async API unintentionally | duplicate runtime ownership | pick one surface per process |
+| Fire write commands without commit session | partial or rejected mutations | always bracket writes with commit APIs |
+| Hardcode unsupported commands | `AS_UNHANDLED` at runtime | map/handle `RunActionStatus` and runtime flags |
+
+## Async vs Blocking Selection
+
+| Requirement | Preferred API |
+| --- | --- |
+| Tokio app / async daemon | `KiCadClient` |
+| Existing sync binary | `KiCadClientBlocking` |
+| Lowest integration friction for scripts | `KiCadClientBlocking` + CLI |
+
+## Reliability Checklist
+
+- Set explicit `client_name` for traceability.
+- Keep request timeout defaults unless measured need.
+- Handle transport + protocol errors as recoverable boundary.
+- Use typed wrappers when available; drop to raw only when needed.

docs/book/src/validation.md

@@ -0,0 +1,27 @@
+# Validation and Testing
+
+Before handoff or release:
+
+```bash
+cargo fmt --all
+cargo test
+cargo test --features blocking
+```
+
+## Evidence Pointers
+
+- Unit tests across client/model/blocking/CLI parser paths:
+  - [`src/client.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/client.rs)
+  - [`src/blocking.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/blocking.rs)
+  - [`src/model/common.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/model/common.rs)
+  - [`src/model/board.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/model/board.rs)
+  - [`test-scripts/kicad-ipc-cli.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/test-scripts/kicad-ipc-cli.rs)
+- Runtime command coverage matrix:
+  - [README coverage section](https://github.com/Milind220/kicad-ipc-rs#kicad-v10-rc11-api-completion-matrix)
+- Runtime CLI verification flow:
+  - [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)
+
+## CI Notes
+
+- API/release pipeline: `.github/workflows/release-plz.yml`
+- Book deploy pipeline: `.github/workflows/mdbook.yml`