docs: add MkDocs Material site with GitHub Pages CI and policy checks

.env.example

@@ -1,5 +1,9 @@
 # Copy to .env and adjust for your environment:
 #   cp .env.example .env
+#
+# Full variable reference (authoritative):
+#   https://ndevu12.github.io/Research_Assistant_Model/configuration/environment-variables/
+#   or docs/configuration/environment-variables.md in the repo
 
 # =============================================================================
 # Retrieval APIs (optional)
@@ -25,6 +29,7 @@ RA_LLM__PROVIDER=ollama
 RA_LLM__MODEL=auto
 # RA_LLM__MODEL=llama3.1:8b
 
+# With or without /v1 — Ollama providers normalize via normalize_openai_base_url()
 RA_LLM__BASE_URL=http://localhost:11434/v1
 RA_LLM__API_KEY=ollama
 # OLLAMA_API_KEY=ollama

.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'contributing.md'
+      - 'scripts/check_docs_policy.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'contributing.md'
+      - 'scripts/check_docs_policy.py'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install docs tooling
+        run: pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin linkchecker
+
+      - name: Docs policy (scaffold rejection)
+        run: python scripts/check_docs_policy.py
+
+      - name: Build site
+        env:
+          NO_MKDOCS_2_WARNING: 1
+        run: mkdocs build --strict
+
+      - name: Check internal links
+        run: |
+          linkchecker \
+            --no-warnings \
+            --ignore-url="^https://github.com/" \
+            --ignore-url="^https://pypi.org/" \
+            --ignore-url="^https://pipenv.pypa.io/" \
+            --ignore-url="^https://squidfunk.github.io/" \
+            --ignore-url="^https://unpkg.com/" \
+            --ignore-url="^https://api\." \
+            --ignore-url="^https://doi.org/" \
+            --ignore-url="^https://www\.crossref\.org/" \
+            --ignore-url="^https://openalex.org/" \
+            --ignore-url="^https://www\.semanticscholar\.org/" \
+            --ignore-url="^https://arxiv\.org/" \
+            --ignore-url="^https://ollama\.com/" \
+            site/index.html
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -61,3 +61,7 @@ reports/
 # Python cache
 __pycache__/
 pytest_cache/
+
+# MkDocs build output
+site/
+.cache/

Pipfile

@@ -24,6 +24,10 @@ torch = {version = "*", index = "pytorch-cpu"}
 rich = "*"
 
 [dev-packages]
+mkdocs = "*"
+mkdocs-material = "*"
+mkdocs-mermaid2-plugin = "*"
+linkchecker = "*"
 
 [requires]
 python_version = "3.13"

README.md

@@ -4,6 +4,8 @@ A local-first research pipeline that retrieves academic papers from multiple sch
 
 Built with Python 3.13, pydantic-ai, sentence-transformers, and async I/O.
 
+**Documentation:** [https://ndevu12.github.io/Research_Assistant_Model/](https://ndevu12.github.io/Research_Assistant_Model/) — architecture, configuration, API, operations, and known issues.
+
 ## Features
 
 - **Multi-stage pipeline** — query understanding → expansion → retrieval → deduplication → ranking → clustering → synthesis → gap analysis → citation export → report generation

contributing.md

@@ -0,0 +1,75 @@
+# Contributing
+
+Thank you for improving the AI Research Assistant. This file is the **canonical contributor entry** for GitHub — the docs site links here rather than duplicating it.
+
+**Full documentation:** https://ndevu12.github.io/Research_Assistant_Model/
+
+## Code contributions
+
+### Setup
+
+```bash
+pipenv install --dev
+pipenv run pytest
+```
+
+See the docs site for [local development setup](https://ndevu12.github.io/Research_Assistant_Model/development/local-setup/) and [testing](https://ndevu12.github.io/Research_Assistant_Model/development/testing/).
+
+### Guidelines
+
+1. Run `pipenv run pytest -m "not slow"` before opening a PR.
+2. Match existing import and module layout — see [import conventions](https://ndevu12.github.io/Research_Assistant_Model/development/import-conventions/).
+3. Keep changes focused; avoid unrelated refactors in the same PR.
+4. Add or update tests when behavior changes.
+
+## Documentation contributions
+
+Documentation is published with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) from the `docs/` directory.
+
+### Local preview
+
+```bash
+pipenv install --dev
+pipenv run mkdocs serve
+# → http://127.0.0.1:8000/Research_Assistant_Model/
+```
+
+Build without serving (same checks as CI):
+
+```bash
+pipenv run mkdocs build --strict
+pipenv run python scripts/check_docs_policy.py
+```
+
+### File location policy
+
+| Location | Role |
+|----------|------|
+| Root `README.md`, `contributing.md` | GitHub landing and contributor entry — **stay at repo root** |
+| `docs/` | Deep, code-backed reference pages for the docs site |
+| `docs/contributing.md` | Short pointer to this file only |
+
+**Do:** write new deep content in `docs/` from code analysis; link getting-started pages to the root README for copy-paste commands.
+
+**Do not:** move or gut root README/contributing; copy-paste README body into docs pages; ship scaffold placeholders (CI rejects them).
+
+### Writing conventions
+
+1. **Reference pattern:** Docs pages link to the root README for quick-start commands; add internals and analysis below the link.
+2. **Admonition types:** `warning` for stubs/known bugs, `tip` for cookbooks, `info` for defaults.
+3. **Code paths:** Use `pipenv run python -m src` in examples.
+4. **Config examples:** Show YAML + equivalent `RA_*` env override side-by-side.
+5. **Mermaid:** Use for pipeline/LLM diagrams; keep node IDs camelCase.
+6. **Status tags:** Mark API and stub providers as experimental or planned.
+
+Authoritative references:
+
+| Topic | Docs page |
+|-------|-----------|
+| Canonical sources (command blocks, warnings) | [reference/canonical-sources.md](https://ndevu12.github.io/Research_Assistant_Model/reference/canonical-sources/) |
+| Known issues | [quality/known-issues.md](https://ndevu12.github.io/Research_Assistant_Model/quality/known-issues/) |
+| Setup system | [setup-system/index.md](https://ndevu12.github.io/Research_Assistant_Model/setup-system/) |
+| Publishing / CI | [development/publishing.md](https://ndevu12.github.io/Research_Assistant_Model/development/publishing/) |
+| Environment variables | [configuration/environment-variables.md](https://ndevu12.github.io/Research_Assistant_Model/configuration/environment-variables/) |
+
+The legacy file `docs/research-quality-known-issues.md` is a redirect only; edit `docs/quality/known-issues.md`.

docs/_analysis/README.md

@@ -0,0 +1,23 @@
+# Phase 0 — Code Analysis Artifacts
+
+Internal reference produced from source and test analysis. **Not published** in the MkDocs site nav — use these artifacts when writing user-facing pages in Phase 1+.
+
+| Artifact | Purpose | Primary consumers |
+|----------|---------|-------------------|
+| [artifact-registry.md](artifact-registry.md) | Pipeline stage I/O, artifacts, config keys, LLM usage | `architecture/pipeline-stages.md`, `architecture/overview.md`, `configuration/stage-toggles.md` |
+| [config-inventory.md](config-inventory.md) | `AppSettings` fields, YAML files, env vars, precedence | `configuration/*`, `getting-started/*` |
+| [test-behavior-index.md](test-behavior-index.md) | Test map, mocks, coverage gaps | `development/testing.md` |
+| [provider-http-matrix.md](provider-http-matrix.md) | Retrieval provider HTTP details, CLI vs pipeline | `retrieval/*`, `operations/troubleshooting.md` |
+| [llm-resolution-tree.md](llm-resolution-tree.md) | LLM provider/model/feature resolution | `llm/*`, `architecture/llm-layer.md` |
+
+**Generated:** 2026-05-22  
+**Source revision:** analyzed against current `main` tree (`src/`, `config/`, `tests/`).
+
+## Key findings (executive summary)
+
+1. **11 pipeline stages** share artifacts via `PipelineContext`; final `ResearchPipelineResult.artifacts` exports a subset (see artifact registry).
+2. **CLI shortcut** (`run_research_helper`) hardcodes OpenAlex + Semantic Scholar — differs from full pipeline/API.
+3. **Heuristic LLM defaults** (`synthesis.llm_enabled: false`, `query_expansion.llm_enabled: false`) resolved at pipeline start via `resolve_effective_settings()`.
+4. **3 retrieval stubs** (PubMed, CORE, DBLP) raise `NotImplementedError` if enabled.
+5. **Config precedence:** constructor kwargs > process env > `.env` > merged YAML > field defaults; plus post-load LLM feature resolution.
+6. **Doc/code gaps to fix in Phase 1:** `llm.timeout_seconds` and `llm.temperature` unused; per-provider `limit` ignored by `RetrievalStage`; `.env.example` enables `RA_DEBUG=1` while `RA_PIPELINE__DEBUG=false`.