docs: rewrite site on Zensical with runnable examples

.github/PERMISSIONS.md

@@ -133,12 +133,12 @@ permissions:
 
 **Why These Permissions:**
 - `pages: write` - Allows the workflow to:
-  - Deploy the generated MkDocs static site to GitHub Pages
+  - Deploy the generated Zensical static site to GitHub Pages
   - Update the Pages deployment for the repository
 - `id-token: write` - Allows secure OIDC auth for Pages deployment
 
 **What It Does:**
-- Builds MkDocs docs
+- Builds Zensical docs
 - Deploys docs to GitHub Pages
 
 ---

.github/workflows/publish-docs.yml

@@ -18,7 +18,7 @@ permissions:
 
 jobs:
   build-docs:
-    name: Build docs (MkDocs)
+    name: Build docs (Zensical)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -40,9 +40,9 @@ jobs:
         run: |
           uv sync --only-group docs --no-install-project --python 3.13
 
-      - name: Build MkDocs site
+      - name: Build Zensical site
         run: |
-          uv run --no-sync mkdocs build
+          uv run --no-sync zensical build --clean
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

.gitignore

@@ -189,7 +189,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# zensical documentation
 /site
 
 # mypy

AGENTS.md

@@ -190,3 +190,71 @@ What this means in practice:
 
 This rule binds human contributors and AI agents equally, and overrides any
 agent default that biases toward minimal or expedient changes.
+
+---
+
+## I-8: Docs examples show both field-declaration styles
+
+Ferro supports two equivalent ways to declare model fields: assignment
+(`name: str = Field(unique=True)`) and `Annotated` metadata
+(`name: Annotated[str, Field(unique=True)]`). Every documentation example
+that declares model fields with `Field()`/`FerroField()` options must show
+**both** styles, side by side, as content tabs:
+
+    === "Assignment"
+
+        ```python
+        --8<-- "docs/examples/<example>.py:models"
+        ```
+
+    === "Annotated"
+
+        ```python
+        --8<-- "docs/examples/<example>_annotated.py:models"
+        ```
+
+Rules:
+
+- Both tabs must be backed by real, runnable code. Snippet-embedded model
+  definitions get a runnable `<name>_annotated.py` companion in
+  `docs/examples/` (exercised by `tests/test_docs_examples.py`); inline
+  blocks are written in both styles and compile-checked by the same test.
+- Constructs with only one valid form appear identically in both tabs and
+  are not tabbed on their own: forward FKs are always
+  `Annotated[Target, ForeignKey(...)]`, and `BackRef()` / `ManyToMany()`
+  are always assignments.
+- Code blocks that do not declare fields (queries, mutations, transactions,
+  usage snippets) are not affected by this rule.
+
+This keeps users from ever wondering whether something is possible in their
+preferred declaration style.
+
+---
+
+## I-9: Lambda predicates are the official query style
+
+Documentation and examples use the lambda predicate style for all queries:
+
+```python
+adults = await User.where(lambda t: t.age >= 18).all()
+```
+
+Rules:
+
+- **Every query example** in docs, docstring `Examples:` sections, and
+  `docs/examples/` scripts uses lambda predicates.
+- When the predicate styles themselves are documented, present them in
+  order **lambda > `col()` > operator**, with lambda labeled the officially
+  recommended style.
+- **Operator style** (`User.where(User.age >= 18)`) is compatible today but
+  is slated for deprecation in a future release and fails static type
+  checking (`User.age >= 18` types as `bool`; `where()` expects
+  `QueryNode | Predicate`). Docs say so explicitly wherever the style is
+  shown.
+- **`order_by` is not a predicate** and keeps attribute style
+  (`order_by(User.age, "desc")`). Passing a lambda to `order_by` silently
+  produces a junk column name — never show it.
+
+The canonical comparisons live in `docs/pages/guide/queries.md`
+("Predicate Styles") and `docs/pages/concepts/query-typing.md`; everywhere
+else uses lambda without restating the trade-offs.

CONTRIBUTING.md

@@ -37,7 +37,7 @@ This will install all development dependencies including:
 - Testing tools (pytest, pytest-asyncio, pytest-cov)
 - Linting and formatting tools (ruff, prek)
 - Build tools (maturin)
-- Documentation tools (mkdocs-material)
+- Documentation tools (zensical)
 - Release tools (commitizen, python-semantic-release)
 
 ### 3. Install Pre-commit Hooks
@@ -102,10 +102,10 @@ cargo clippy               # Rust linting
 
 ```bash
 # Serve documentation locally (with live reload)
-uv run mkdocs serve
+uv run zensical serve
 
 # Build documentation
-uv run mkdocs build
+uv run zensical build
 
 # Documentation will be available at http://127.0.0.1:8000/
 ```

README.md

@@ -4,7 +4,7 @@
 
 [![PyTest](https://img.shields.io/badge/Pytest-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white)](https://docs.pytest.org/)
 [![Ruff](https://img.shields.io/badge/Ruff-FFC107?style=for-the-badge&logo=python&logoColor=black)](https://docs.astral.sh/ruff/)
-[![MkDocs](https://img.shields.io/badge/MkDocs-000000?style=for-the-badge&logo=markdown&logoColor=white)](https://www.mkdocs.org/)
+[![Zensical](https://img.shields.io/badge/Zensical-4051B5?style=for-the-badge&logo=markdown&logoColor=white)](https://zensical.org/)
 [![UV](https://img.shields.io/badge/UV-2C2C2C?style=for-the-badge&logo=python&logoColor=white)](https://github.com/astral-sh/uv)
 [![Rust](https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org/)
 [![Python](https://img.shields.io/badge/Python-3.13%20|%203.14-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)