Release 1.0.0 baseline, docs workflow, and follow-up assets

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Sync dependencies
+        run: uv sync --frozen --dev
+      - name: Ruff
+        run: uv run ruff check src tests
+      - name: Report regression contracts
+        run: uv run python -m pytest tests/test_quality.py tests/test_report_regressions.py
+      - name: Pytest
+        run: uv run python -m pytest tests

.github/workflows/docs.yml

@@ -0,0 +1,109 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Full history for accurate page timestamps
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dependencies
+        run: |
+          python -m pip install uv
+          uv sync --frozen --dev
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: uv run great-docs build
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: Upload build timings
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-timings
+          path: great-docs/_site/build-timings.json
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  preview-docs:
+    name: "Preview Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'pull_request'
+    permissions:
+      deployments: write
+      pull-requests: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      # Start deployment
+      - name: Configure pull release name
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          echo "RELEASE_NAME=pr-${{ github.event.number }}" >> $GITHUB_ENV
+
+      - name: Configure branch release name
+        if: ${{ github.event_name != 'pull_request' }}
+        run: |
+          # use branch name, but replace slashes. E.g. feat/a -> feat-a
+          echo "RELEASE_NAME=${GITHUB_REF_NAME//\//-}" >> $GITHUB_ENV
+
+      # Deploy
+      - name: Create Github Deployment
+        uses: bobheadxi/deployments@v1
+        id: deployment
+        if: ${{ !github.event.pull_request.head.repo.fork }}
+        with:
+          step: start
+          token: ${{ secrets.GITHUB_TOKEN }}
+          env: ${{ env.RELEASE_NAME }}
+          ref: ${{ github.head_ref }}
+          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"

.gitignore

@@ -8,3 +8,9 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Local docs drafts and private notes
+docs/_drafts/
+
+# Great Docs build output (ephemeral)
+great-docs/

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff-check
+        entry: uv run ruff check src tests
+        language: system
+        pass_filenames: false
+      - id: pytest-tests
+        name: pytest-tests
+        entry: uv run python -m pytest tests
+        language: system
+        pass_filenames: false
+      - id: pytest-report-regressions
+        name: pytest-report-regressions
+        entry: uv run python -m pytest tests/test_quality.py tests/test_report_regressions.py
+        language: system
+        pass_filenames: false

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+Thanks for contributing to `pytest-notebook-policy`.
+
+## Prerequisites
+- Python `3.12+`
+- `uv` for environment and dependency management
+- `just` (optional but recommended for common workflows)
+
+## Quick local workflow
+1. Sync dependencies:
+   - `uv sync --dev`
+2. Run quality gates:
+   - `just qa`
+3. Build docs:
+   - `just docs-build`
+
+## Documentation workflow (Great Docs)
+Use this as the default docs gate before opening a PR:
+
+- `just docs-workflow`
+
+This runs:
+- docs build (`great-docs build`)
+- prepublish link checks with sensible temporary ignores for not-yet-live URLs
+
+For strict enforcement (for example after Pages is live and branch/source links are stable), run:
+
+- `just docs-workflow-strict`
+
+Useful docs commands:
+- `just docs-preview` (local preview with reload)
+- `just docs-scan` (API discovery view)
+- `just docs-setup-pages` (scaffold/refresh GitHub Pages workflow)
+
+## Release-related checks
+Before packaging/release work:
+- `just qa`
+- `just build-check`
+
+## Pull requests
+- Keep changes scoped and explain intent in the PR description.
+- Include validation commands/results for code and docs where relevant.
+- Update docs and release notes when behaviour or user-facing workflows change.

README.md

@@ -67,6 +67,7 @@ This keeps the feedback loop short:
 Detailed rationale and remediation guidance: [`docs/RULES.md`](docs/RULES.md).
 
 ## Usage
+Runtime baseline: Python `3.12+`.
 Install in a project:
 
 ```shell
@@ -198,6 +199,7 @@ uv run pytest-notebook-quality --skip-ruff \
   --report-dependency-enrichment \
   path/to/notebooks
 ```
+Interpret report outputs and tune policy profiles: [`docs/REPORT_INTERPRETATION.md`](docs/REPORT_INTERPRETATION.md).
 
 Project-specific quality defaults can be set in `pyproject.toml`:
 
@@ -221,6 +223,27 @@ Enable optional sync tooling:
 uv add --dev 'pytest-notebook-policy[sync]'
 ```
 
+## Documentation site (Great Docs)
+This repository uses Great Docs for documentation generation and deployment.
+
+Build docs locally:
+
+```shell
+uv run great-docs build
+```
+
+Preview docs locally:
+
+```shell
+uv run great-docs preview
+```
+
+Scaffold or refresh the GitHub Pages workflow:
+
+```shell
+uv run great-docs setup-github-pages
+```
+
 ## Versioning and release workflow
 - Versioning follows Semantic Versioning (`MAJOR.MINOR.PATCH`).
 - Release history lives in `RELEASE_NOTES.md`.

RELEASE_NOTES.md

@@ -5,6 +5,30 @@ This project follows Semantic Versioning (`MAJOR.MINOR.PATCH`).
 ### Changed
 - No unreleased entries yet.
 
+## [1.0.0] - Stable baseline + Great Docs foundation
+### Release intent
+- Mark the first stable major release and establish a modern runtime/docs baseline for ongoing development.
+
+### Highlights
+- Promoted package versioning to `1.0.0`.
+- Raised runtime support baseline to Python `3.12+`.
+- Updated Ruff target configuration to `py312`.
+- Added Great Docs integration for documentation generation and preview workflows.
+- Added GitHub Pages docs workflow scaffold via Great Docs (`.github/workflows/docs.yml`).
+- Expanded CI test matrix to validate against Python `3.12` and `3.13`.
+
+## [0.9.0] - Report UX and NBOM alignment
+### Release intent
+- Improve markdown report readability and operator guidance while keeping machine-readable NBOM output aligned.
+
+### Highlights
+- Refactored markdown report rendering to use a Jinja2 template.
+- Added standard executive summary guidance under the report header.
+- Added short descriptive text under major report sections to clarify purpose and usage.
+- Added Appendix C NBOM alignment summary fields for easier cross-checking against NBOM JSON output.
+- Shifted optional dependency metadata to Appendix D when enrichment is enabled.
+- Added regression assertions for updated report structure and section ordering.
+
 ## [0.8.0] - Planned initial PyPI release
 ### Release intent
 - First public release of `pytest-notebook-policy` to PyPI.

ROADMAP.md

@@ -13,6 +13,16 @@ This document captures likely next steps for `pytest-notebook-policy` after the
   - data source hints
 - Improve docs for report interpretation and policy tuning workflows.
 
+## Immediate easy wins (prioritised)
+1. Improve docs for report interpretation and policy tuning workflows.
+   - Why first: highest user impact for lowest implementation effort.
+2. Tighten pre-commit and CI quality gates around report regressions.
+   - Why second: mostly workflow configuration with fast confidence gains.
+3. Expand example notebooks and fixture coverage for real-world edge cases.
+   - Why third: incremental additions that improve trust and regression safety.
+4. Finalise cleaner multi-notebook report summaries.
+   - Why fourth: contained UX improvement with clear value for teams scanning many notebooks.
+
 ## Dependency and supply-chain visibility
 - Add opt-in dependency enrichment for report output:
   - import-to-package mapping
@@ -32,6 +42,11 @@ This document captures likely next steps for `pytest-notebook-policy` after the
 - Add deeper static analysis patterns while remaining deterministic and fast.
 - Improve rule-level configuration granularity and report drill-down detail.
 - Keep optional advisory features non-gating by default.
+- Add a local LLM Lite notebook-style assessor (optional advisory mode):
+  - runs locally for style/narrative/cohesion recommendations
+  - never auto-applies changes
+  - non-gating by default, designed as guidance/coaching
+  - complements deterministic rules with human-readable improvement suggestions
 
 ## Release and ecosystem readiness
 - Tighten pre-commit and CI quality gates around report regressions.

backlog.md

@@ -0,0 +1,12 @@
+# Backlog
+## Candidate enhancements
+### Optional LLM-powered advisory reporting (non-gating)
+- Status: Backlog
+- Goal: add an optional advisory layer that explains notebook policy findings in more depth (what, why, and suggested remediation), without changing deterministic pass/fail behaviour.
+- Scope:
+  - add markdown report output with enriched guidance per finding
+  - keep deterministic rules as the only enforcement path in CI
+  - allow opt-in local execution only (no external dependency by default)
+- Notes:
+  - this should remain optional and disabled by default
+  - explanations should be treated as guidance, not rule truth

docs/JUST_SETUP.md

@@ -0,0 +1,37 @@
+# Just setup
+This repository includes a `justfile` with common local workflows for validation and release preparation.
+
+## What is Just?
+Just is a command runner similar to `make`, with a simpler syntax.
+
+Official site: https://just.systems
+
+Installation instructions: https://just.systems/man/en/
+
+## Quick start
+From the repository root, list available recipes:
+
+```shell
+just --list
+```
+
+## Key recipes in this repository
+- `just create-manual-examples`: scaffold manual marimo/Jupyter example notebooks in `manual_checks/`.
+- `just refresh-fixtures`: print observed rule-code sets for pinned real fixtures.
+- `just qa`: run Ruff and tests.
+- `just docs-init`: initialise Great Docs configuration (`great-docs.yml`).
+- `just docs-build`: build the docs site into `great-docs/_site`.
+- `just docs-preview`: preview docs locally with live reload.
+- `just docs-scan`: scan discovered exports for API docs coverage.
+- `just docs-setup-pages`: scaffold GitHub Pages workflow via Great Docs.
+- `just docs-check`: prepublish link check (ignores known not-yet-live URLs).
+- `just docs-check-strict`: strict link check with no ignores.
+- `just docs-workflow`: run the default docs build + prepublish checks.
+- `just docs-workflow-strict`: run build + strict checks.
+- `just build-check`: clean artefacts, build, and run `twine check`.
+- `just test-publish-dry-run`: build and validate publish artefacts without uploading.
+
+## Recommended sequence before manual notebook validation
+1. `just create-manual-examples`
+2. `uv run pytest-notebook-quality --skip-ruff manual_checks`
+3. Follow `MANUAL_NOTEBOOK_VALIDATION.md` for remediation and sign-off.