docs: add Zensical documentation site with versioned deployment

Set up a documentation website using Zensical (the actively maintained
drop-in replacement for MkDocs, by the mkdocs-material team) with
versioned docs deployed to GitHub Pages via squidfunk's mike fork.

- Add zensical.toml with collapsible nav, light/dark toggle, search,
  and version switching via mike.
- Add pyproject.toml for uv-managed Python dependencies (zensical,
  squidfunk/mike fork). Contributors preview docs with
  `uv run zensical serve`.
- Add .github/workflows/docs.yml with two deployment paths: prerelease
  docs on push to main, versioned docs on GitHub release publication.
  Skipped on forks.
- Split SETUP.md into installation.md (tabbed install options),
  editor-setup.md, and agent-setup.md for cleaner navigation.
- Add docs/configuration.md as a dedicated config reference with
  complete tables for all config sections.
- Add docs/benchmarks.md with comparison table and links to live
  latency and memory charts.
- Add docs/index.md landing page with centered logo, key features,
  and version jump links.
- Rename project-specific docs to lowercase (cli.md, configuration.md).
- Fix all 25 broken anchor links in roadmap docs.
- Fix missing 0.9.0 link reference in CHANGELOG.md.
- Add roadmap sub-pages and benchmarks to navigation.
- Add formatting.pint to config-schema.json (was missing from schema).
- Add .github/PULL_REQUEST_TEMPLATE.md with contributor checklist.
- Update DEFAULT_CONFIG_CONTENT with helpful comments and docs link.
- Simplify README.md documentation section to link to docs site.
- Update docs/CONTRIBUTING.md with docs build instructions.
- Add site/ and .venv/ to .gitignore.

Author: calebdw

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'zensical.toml'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  # Only deploy from the upstream repo, not from forks (forks don't
+  # have write access to gh-pages and would fail).
+  deploy-prerelease:
+    if: github.repository_owner == 'PHPantom-dev' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy prerelease docs
+        env:
+          MKDOCS_SITE_NAME: "PHPantom Docs (prerelease)"
+          MKDOCS_PRIMARY_COLOR: "blue grey"
+        run: uv run -- mike deploy --push --update-aliases prerelease
+
+  deploy-release:
+    if: github.repository_owner == 'PHPantom-dev' && github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy versioned docs
+        run: |
+          version="${GITHUB_REF_NAME}"
+          uv run -- mike deploy --push --update-aliases "$version" latest
+          uv run -- mike set-default --push latest

.gitignore

@@ -9,3 +9,5 @@ sandbox.php
 examples/laravel/.codelite/laravel.session
 .codelite/
 examples/laravel/.codelite/
+/site/
+/.venv/

README.md

@@ -91,14 +91,7 @@ PHPantom understands Composer projects out of the box, but works without setup o
 
 ## Documentation
 
-- **[Installation & Configuration](docs/SETUP.md).** Editor setup, project configuration (`.phpantom.toml`), and formatting.
-- **[CLI Reference](docs/CLI.md).** Batch diagnostics (`analyze`), automated fixes (`fix`), and CI integration.
-- **[Building from Source](docs/BUILDING.md).** Build, test, and debug instructions.
-- **[Architecture](docs/ARCHITECTURE.md).** Symbol resolution, stub loading, and inheritance merging.
-- **[Contributing](docs/CONTRIBUTING.md)**
-- **[Changelog](docs/CHANGELOG.md)**
-- **Benchmarks.** [Latency](https://phpantom-dev.github.io/phpantom_lsp/dev/bench/) and [memory usage](https://phpantom-dev.github.io/phpantom_lsp/dev/memory/) tracked on every commit.
-- **[Roadmap](docs/todo.md).** Planned features and domain-specific plans.
+**[Read the docs](https://phpantom-dev.github.io/phpantom_lsp/)** -- installation, editor setup, configuration reference, CLI usage, benchmarks, and more.
 
 ## Acknowledgements
 

docs/BUILDING.md

@@ -63,4 +63,4 @@ RUST_LOG=debug cargo run 2>phpantom.log
 
 Logs are written to stderr, so redirect as needed.
 
-For editor setup instructions, see [SETUP.md](SETUP.md).
+For editor setup instructions, see [Editor Setup](editor-setup.md).

docs/CHANGELOG.md

@@ -36,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
-- **Bundled Zed extension.** PHPantom's plain-PHP wiring has merged into Zed's official PHP extension, so a separate PHPantom extension is no longer needed. See [SETUP.md](SETUP.md) for the updated Zed configuration.
+- **Bundled Zed extension.** PHPantom's plain-PHP wiring has merged into Zed's official PHP extension, so a separate PHPantom extension is no longer needed. See [Editor Setup](editor-setup.md) for the updated Zed configuration.
 
 ### Fixed
 
@@ -824,7 +824,8 @@ Initial release.
 - **Embedded phpstorm-stubs.**
 - **Zed editor extension.**
 
-[Unreleased]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.8.0...HEAD
+[Unreleased]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.9.0...HEAD
+[0.9.0]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.8.0...0.9.0
 [0.8.0]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.7.0...0.8.0
 [0.7.0]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.6.0...0.7.0
 [0.6.0]: https://github.com/PHPantom-dev/phpantom_lsp/compare/0.5.0...0.6.0

docs/CONTRIBUTING.md

@@ -45,10 +45,39 @@ See [BUILDING.md](BUILDING.md) for more on running tests and manual LSP testing.
 
 Update [CHANGELOG.md](CHANGELOG.md) when your PR adds, changes, or fixes something a user would notice. Add entries under `## [Unreleased]` in the appropriate subsection (`### Added`, `### Fixed`, `### Changed`, or `### Removed`). Write for end users, not developers: describe what changed in the editor, not which internal modules were touched. See the existing entries for the style and level of detail expected.
 
+## Documentation
+
+The documentation site is built with [Zensical](https://zensical.org/).
+The only dependency you need is [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+Preview the docs locally with live reload:
+
+```bash
+uv run zensical serve
+```
+
+Then open `http://127.0.0.1:8000` in your browser. Changes to files in
+`docs/` and `zensical.toml` are reflected immediately. If port 8000 is
+already in use, pick a different one:
+
+```bash
+uv run zensical serve -a 127.0.0.1:8200
+```
+
+Build the docs for offline use:
+
+```bash
+uv run zensical build
+```
+
+The output is written to `site/` (gitignored). `uv` handles creating
+a virtual environment and installing all Python dependencies
+automatically on first run.
+
 ## Reporting Issues
 
 Open an issue on GitHub with:
 
 - What you expected to happen
 - What actually happened
-- Steps to reproduce (a minimal PHP snippet is ideal)
+- Steps to reproduce (a minimal PHP snippet is ideal)