chore - add Prismplane docs site and strict docs CI (#9)

.github/pull_request_template.md

@@ -9,7 +9,7 @@ What does this PR change, and why?
 - [ ] Refactor / maintenance
 - [ ] Documentation
 - [ ] CI / tooling
-- [ ] RFC (adds/updates `docs/rfcs/*`)
+- [ ] RFC (adds/updates `docs/rfcs/**`)
 
 ## Area(s)
 

.github/workflows/docs.yml

@@ -0,0 +1,94 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "examples/tutorial_book/**"
+      - "tests/docs/**"
+      - "utils/**"
+      - "Makefile"
+      - "mkdocs_hooks.py"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "examples/tutorial_book/**"
+      - "tests/docs/**"
+      - "utils/**"
+      - "Makefile"
+      - "mkdocs_hooks.py"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  mkdocs:
+    name: MkDocs strict build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out IncQL
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install docs dependencies
+        run: python -m pip install -r requirements-docs.txt
+
+      - name: Build docs
+        run: make docs-build
+
+  deploy-pages:
+    name: Deploy docs to GitHub Pages
+    needs: mkdocs
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out IncQL
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install docs dependencies
+        run: python -m pip install -r requirements-docs.txt
+
+      - name: Configure deploy identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish docs
+        run: mkdocs gh-deploy --force --strict --remote-branch gh-pages --message "chore - deploy docs site"

AGENTS.md

@@ -69,7 +69,7 @@ Normative behavior is defined in **`docs/rfcs/`**. If package code and an RFC di
 ## General workflow
 
 1. **Branch from `main`**: Prefer `<type>/<issue>-<slug>` (e.g. `feature/8-rfc-table-automation`, `docs/9-mkdocs-ci`), matching team practice.
-2. **Follow RFCs**: Behavior changes should be reflected in the right `docs/rfcs/*.md` (or a new RFC) before or alongside code in the appropriate repository.
+2. **Follow RFCs**: Behavior changes should be reflected in the right RFC under `docs/rfcs/` (or a new RFC) before or alongside code in the appropriate repository.
 3. **Run the local gate**: `make ci` (or at least `make fmt-check`, `make build`, `make test`) before considering work done for **this** repo.
 4. **Version sync**: If you bump the package version, update **both** [incan.toml][incan-toml] (`[project] version`) and [src/metadata.incn][metadata-incn] (`incql_version()`) in the same commit (see [CONTRIBUTING.md][contributing]).
 5. **Documentation**: User-facing or spec changes should update `README.md`, relevant `docs/*`, or RFCs as appropriate. Keep prose markdown **without hard wrapping** (natural paragraphs).

CONTRIBUTING.md

@@ -14,6 +14,7 @@ Thank you for your interest in IncQL — the typed relational layer for [Incan][
 | [Incan `CONTRIBUTING.md`][incan-contributing] | Compiler, tooling, and Rust workspace workflow |
 | [Incan docs-site contributor loop][incan-docsite-loop] | Divio layout, snippets, checklist for Incan’s MkDocs site — mirror these patterns when shaping IncQL `docs/` |
 | [Incan AGENTS — Docs-site workflow][incan-agents-docs-workflow] | Prose **without hard wrapping**, `mkdocs build --strict`, Material-friendly Markdown |
+| [Prismplane docs theme][prismplane-theme] | IncQL-specific docs visual rules adapted from the local Prismplane prototype |
 
 **Compiler and language implementation** (lexer, parser, typechecker, lowering, codegen for `query {}` and related surfaces) lives in the **Incan** repository. Use that project’s docs and gates when you change the toolchain. Use **this** repo for the IncQL **library source** (`.incn`) and **IncQL RFCs** that specify the relational surface.
 
@@ -48,6 +49,21 @@ Thank you for your interest in IncQL — the typed relational layer for [Incan][
 
    With `incan` on your `PATH` you can call `incan build --lib` and `incan test tests` directly (use the `tests/` path so a sibling Incan checkout under `./incan/` is not collected). Override the binary with `make build INCAN=/path/to/incan` if needed.
 
+4. **Build the documentation site**
+
+   Install the pinned docs dependencies and run a strict build before opening documentation-heavy PRs:
+
+   ```bash
+   python -m pip install -r requirements-docs.txt
+   mkdocs build --strict
+   ```
+
+   Use `mkdocs serve` for local preview while editing. The GitHub Actions docs workflow runs the same strict build for changes under `docs/`, `mkdocs.yml`, `requirements-docs.txt`, or the workflow itself.
+
+5. **Preview or publish the documentation site**
+
+   The public documentation site is published at [encero-systems.github.io/IncQL/][docs-site]. The docs workflow publishes to the `gh-pages` branch after a successful strict build on `main` or manual dispatch. Repository Pages settings should use **Deploy from a branch**, branch `gh-pages`, folder `/ (root)`.
+
 ## Project structure
 
 See [docs/architecture.md][architecture] for a concise map. In short:
@@ -56,6 +72,8 @@ See [docs/architecture.md][architecture] for a concise map. In short:
 - `src/*.incn` — library modules; `lib.incn` re-exports the public surface
 - `tests/` — Incan tests for the package
 - `docs/rfcs/` — design specifications (numbered separately from Incan’s RFC index)
+- `mkdocs.yml` — documentation site navigation and strict-build configuration
+- `requirements-docs.txt` — pinned Python dependencies for local and CI docs builds
 
 ## Changing behavior
 
@@ -163,3 +181,5 @@ Open an issue on this repository for IncQL-specific design or package questions;
 [issue-templates]: .github/ISSUE_TEMPLATE/
 [incan-docsite-loop]: https://github.com/encero-systems/incan/blob/main/workspaces/docs-site/docs/contributing/tutorials/book/08_docsite_contributor_loop.md
 [incan-agents-docs-workflow]: https://github.com/encero-systems/incan/blob/main/AGENTS.md#docs-site-workflow-mkdocs-material
+[prismplane-theme]: docs/contributing/prismplane_docs_theme.md
+[docs-site]: https://encero-systems.github.io/IncQL/

Makefile

@@ -9,6 +9,23 @@
 INCAN ?= incan
 export INCAN_NO_BANNER ?= 1
 
+TUTORIAL_BOOK_DIR := examples/tutorial_book
+TUTORIAL_BOOK_CHAPTERS := \
+	src/chapter_01.incn \
+	src/chapter_02.incn \
+	src/chapter_03.incn \
+	src/chapter_04.incn \
+	src/chapter_05.incn \
+	src/chapter_06.incn \
+	src/chapter_07.incn \
+	src/chapter_08.incn \
+	src/chapter_09.incn
+
+TUTORIAL_BOOK_RUNNABLES := \
+	src/main.incn \
+	src/chapter_08.incn \
+	src/chapter_09.incn
+
 .DEFAULT_GOAL := help
 
 .PHONY: help
@@ -66,6 +83,42 @@ test-locked: ## Run tests with `--locked`
 	@echo "\033[1mRunning IncQL tests (locked)...\033[0m"
 	@$(INCAN) test $(INCQL_TEST_DIR) --locked
 
+# =============================================================================
+# Documentation
+# =============================================================================
+
+.PHONY: rfc-index
+rfc-index: ## Validate RFC metadata and regenerate the RFC catalog
+	@python3 utils/rfc_catalog.py --tags docs/rfcs/catalog.json --write
+
+.PHONY: rfc-index-check
+rfc-index-check: ## Validate RFC metadata and fail when the catalog is stale
+	@python3 utils/rfc_catalog.py --tags docs/rfcs/catalog.json --check
+
+.PHONY: docs-test
+docs-test: ## Run documentation tooling unit tests
+	@python3 -m unittest discover -s tests/docs -p 'test_*.py'
+	@node --test tests/docs/test_rfc_reader.cjs
+
+.PHONY: docs-build
+docs-build: rfc-index-check docs-test ## Validate and build the documentation site strictly
+	@mkdocs build --strict
+
+.PHONY: tutorial-book
+tutorial-book: ## Type-check every tutorial chapter and run each complete learning path
+	@echo "\033[1mChecking IncQL tutorial-book chapters...\033[0m"
+	@cd $(TUTORIAL_BOOK_DIR) && $(INCAN) lock >/dev/null
+	@for script in $(TUTORIAL_BOOK_CHAPTERS); do \
+		echo "\033[1m  -> $$script\033[0m"; \
+		cd $(TUTORIAL_BOOK_DIR) && $(INCAN) --check "$$script" || exit $$?; \
+		cd ../..; \
+	done
+	@for script in $(TUTORIAL_BOOK_RUNNABLES); do \
+		echo "\033[1m  -> run $$script\033[0m"; \
+		cd $(TUTORIAL_BOOK_DIR) && $(INCAN) run "$$script" --locked || exit $$?; \
+		cd ../..; \
+	done
+
 # =============================================================================
 # Formatting (Incan source)
 # =============================================================================
@@ -76,7 +129,7 @@ test-locked: ## Run tests with `--locked`
 # packages are listed by source directory so generated `target/` output stays
 # outside the formatting walk.
 
-INCQL_FMT_DIRS := src tests examples/advanced_retail_query_blocks/src
+INCQL_FMT_DIRS := src tests examples/advanced_retail_query_blocks/src examples/tutorial_book/src
 INCQL_FMT_FILES := examples/*.incn
 
 .PHONY: fmt

README.md

@@ -1,12 +1,12 @@
 # IncQL
 
-**IncQL** is the **typed data logic plane** for [Incan](https://github.com/encero-systems/incan): the place where you express **relational queries**, **schema-aware table transformations**, and **streaming-shaped relational work** with compile-time checks, without folding orchestration, catalogs, or engine-specific runtime into the authoring model. Row shapes come from Incan `model` types; column, join, and alias rules are part of one semantic core whether you use `query { }` blocks, method chains on `DataSet[T]` carriers, or (later) optional pipe-forward (`|>`).
+**IncQL** is the **typed data logic plane** for governed relational work, implemented as an [Incan](https://github.com/encero-systems/incan) library package. It is where you express **relational queries**, **schema-aware table transformations**, and **streaming-shaped relational work** with compile-time checks, without folding orchestration, catalogs, or engine-specific runtime into the authoring model. Row shapes come from Incan `model` types; column, join, and alias rules are part of one semantic core whether you use `query { }` blocks, method chains on `DataSet[T]` carriers, or (later) optional pipe-forward (`|>`).
 
 **What IncQL is not:** It is not a pipeline or workflow framework, not a semantic catalog, and not a catch-all that swallows execution concerns. It owns **data logic**: query authoring, relational plan shape, resolution and schema flow, typed carrier semantics, and **backend-neutral logical intent**. Execution, binding, and operational semantics live in the layer below (session, adapters, runners).
 
-**Why it matters:** Raw SQL strings and untyped rows defer mistakes to runtime. IncQL keeps relational work **in the language**: schemas are ordinary models, invalid references and many aggregation mistakes are caught where Incan promises checking, and plans are intended to lower to **Apache Substrait** so logical intent stays portable while credentials and physical reads are resolved outside the normative plan story.
+**Why it matters:** Raw SQL strings and untyped rows defer mistakes to runtime. IncQL keeps relational work **in source**: schemas are ordinary models, invalid references and many aggregation mistakes are caught by the typechecked authoring surface, and plans are intended to lower to **Apache Substrait** so logical intent stays portable while credentials and physical reads are resolved outside the normative plan story.
 
-**Bottom line:** IncQL is where you write **checked relational logic** in Incan: the same naming and schema rules apply to `query { }` blocks and `DataSet[T]` APIs, and **execution stays downstream** (sessions, adapters, runners) and consistent.
+**Bottom line:** IncQL provides **checked relational logic** for data systems: the same naming and schema rules apply to `query { }` blocks and `DataSet[T]` APIs, and **execution stays downstream** (sessions, adapters, runners) and consistent.
 
 ## What you get
 
@@ -19,6 +19,8 @@
 
 Design is **RFC-driven**; **[docs/rfcs/](docs/rfcs/README.md)** is the source of truth.
 
+Documentation site: **https://encero-systems.github.io/IncQL/**
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and [architecture.md](docs/architecture.md) for how this repo relates to the Incan compiler.
@@ -46,7 +48,8 @@ Normative proposals live under **[docs/rfcs/](docs/rfcs/README.md)**. IncQL’s
 - `src/lib.incn` — public exports
 - `src/` — library modules
 - `tests/` — tests
-- `.github/workflows/` — CI (builds the pinned Incan release branch, then runs IncQL checks)
+- `mkdocs.yml` — documentation site configuration for the `docs/` tree
+- `.github/workflows/` — CI for package checks, strict docs builds, and GitHub Pages deployment
 
 Build and test from this repo root (with `incan` on your `PATH`):
 
@@ -61,4 +64,4 @@ incan build --lib
 incan test tests
 ```
 
-See `make help` for other targets (`fmt`, `fmt-check`, `registry-metadata`, `build-locked`, …). Continuous integration builds **Incan from source** from the workflow's pinned `INCAN_REF` release branch or tag, then runs `fmt-check`, `test-style`, function registry metadata validation, `build`, `test`, and the pub-consumer smoke check (see [.github/workflows/ci.yml](.github/workflows/ci.yml)).
+See `make help` for other targets (`fmt`, `fmt-check`, `registry-metadata`, `build-locked`, …). Continuous integration builds **Incan from source** from the workflow's pinned `INCAN_REF` release branch or tag, then runs `fmt-check`, `test-style`, function registry metadata validation, `build`, `test`, and the pub-consumer smoke check (see [.github/workflows/ci.yml](.github/workflows/ci.yml)). The docs workflow runs `mkdocs build --strict` for documentation changes and publishes the site to GitHub Pages from `main` or manual dispatch; see [CONTRIBUTING.md](CONTRIBUTING.md) for the local docs build loop.