Make contributing easier and add a stable CI gate

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,14 @@
+---
+name: Bug report
+about: Report incorrect behavior or a crash
+---
+
+## Command and CPython version
+
+## Minimal source that reproduces the bug
+
+## Expected behavior
+
+## Actual behavior
+
+Remove credentials and private data before sharing source or logs.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,10 @@
+---
+name: Feature request
+about: Suggest a change to Aiython
+---
+
+## Problem or use case
+
+## Proposed behavior
+
+## Small example

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What changed
+
+<!-- Describe the behavior and why it changed. -->
+
+## How you tested it
+
+<!-- Include commands or a small reproduction. Note any checks you could not run. -->
+
+## Documentation
+
+<!-- Link updated docs/examples, or say why no update is needed. -->

.github/workflows/tests.yml

@@ -2,6 +2,7 @@ name: Offline tests
 
 on:
   push:
+    branches: [main]
   pull_request:
 
 permissions:
@@ -81,3 +82,34 @@ jobs:
             uuid-dev zlib1g-dev libnsl-dev libtirpc-dev
       - name: Build and test patched CPython
         run: uv run --locked --python ${{ matrix.python-version }} python scripts/build_cpython_hooks.py ${{ matrix.python-version }}
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.11.16"
+          version: latest-known
+          enable-cache: false
+      - run: uv run --locked --python 3.11.16 zensical build --clean --strict
+      - run: uv run --locked --python 3.11.16 python scripts/check_docs_site.py
+
+  required:
+    name: CI
+    if: ${{ always() }}
+    needs: [package, test, native-hooks, docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every job to pass
+        env:
+          PACKAGE: ${{ needs.package.result }}
+          TEST: ${{ needs.test.result }}
+          NATIVE_HOOKS: ${{ needs.native-hooks.result }}
+          DOCS: ${{ needs.docs.result }}
+        run: |
+          for result in "$PACKAGE" "$TEST" "$NATIVE_HOOKS" "$DOCS"; do
+            test "$result" = success || exit 1
+          done

CONTRIBUTING.md

@@ -1,51 +1,45 @@
 # Contributing to Aiython
 
-Thanks for helping improve Aiython. Bug reports, documentation fixes, examples,
-and focused code changes are welcome.
+Bug reports, documentation fixes, examples, and focused code changes are welcome.
 
-## Before you change code
+## Start with an issue
 
-- Search existing issues and pull requests for related work. For a larger change,
-  open an issue first so the behavior and scope can be discussed.
-- Keep Python in charge of execution order and side effects. New behavior should
-  apply generally, rather than depend on a particular prompt or example.
-- Keep code, examples, documentation, and user-facing messages in English.
+Search existing issues and pull requests first. For a larger change, open an
+issue to discuss the behavior before writing code. A bug report should include
+the Aiython command, CPython version, expected and actual behavior, and a small
+reproducible script. Remove credentials and private data from logs and examples.
 
-## Develop locally
+## Make a change
 
-Install CPython 3.11+ and [uv](https://docs.astral.sh/uv/), then run:
+Fork the repository and create a branch from `main`, such as `fix/error-message`
+or `docs/getting-started`. Install CPython 3.11+ and [uv](https://docs.astral.sh/uv/):
 
 ```bash
-uv sync
-uv run aiython --explain examples/recipes/03_loop.py
-uv run python -m unittest discover -s tests -q
+uv sync --locked
+uv run --locked aiython --explain examples/recipes/03_loop.py
+uv run --locked python -m unittest discover -s tests -q
 ```
 
-The default test suite mocks provider calls and requires no API key. Use
-`--explain` to inspect an example without executing it. If a change affects a
-provider or capability, add an offline contract test for its request, response,
-and error behavior; live API checks are optional and may incur charges.
-
-The documentation website uses the Markdown files in `docs/`. Preview it with
-`uv run zensical serve` and check the production build with
-`uv run zensical build --clean --strict`, then run
-`uv run python scripts/check_docs_site.py` to check rendered examples and links.
-The public site is built from a release tag after the PyPI publish job succeeds.
-It is served from the separate public
-`aiython-docs` repository; this source repository remains private. Link to pages
-inside `docs/` rather than private repository files.
-
-## Submit a change
-
-Keep a pull request focused and describe the user-visible behavior, why it
-changed, and how you verified it. Update the README or relevant guide when an
-interface changes. Include a small reproducible program for runtime bugs and
-check that Python statements and side effects still run in their normal order.
-
-For a bug report, include the Aiython command, expected and actual behavior,
-Python version, and a minimal source file. `--stats` output can help locate
-latency or provider errors. Remove API keys, credentials, and private input
-before sharing logs or source.
-
-By contributing, you agree that your contribution is licensed under the
-[MIT license](LICENSE).
+The local tests mock provider calls and need no API key. Use `--explain` to
+inspect AI boundaries without running the program. When changing a capability
+or provider, add an offline test for its request, response, and error behavior.
+
+For documentation changes, run:
+
+```bash
+uv run --locked zensical build --clean --strict
+uv run --locked python scripts/check_docs_site.py
+```
+
+## Open a pull request
+
+Push your branch and open a pull request against `main`. Explain what changed,
+why, and how you tested it. Update a relevant guide or example when behavior
+changes. Keep Python in charge of execution order and side effects, and keep
+code and documentation in English.
+
+`main` accepts changes through pull requests. CI checks the package, docs,
+Python 3.11–3.14, and patched CPython hooks before a merge. The release workflow
+publishes PyPI and the documentation site from version tags.
+
+Contributions are licensed under the [MIT license](LICENSE).

README.md

@@ -47,4 +47,6 @@ aiython app.py
 
 The same works for modules: `python -m package` → `aiython -m package`. Your script and its arguments stay the same. Aiython checks declared types and can call AI for inline requests or eligible errors.
 
-Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. [MIT licensed](LICENSE).
+Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider.
+
+[Contributing](CONTRIBUTING.md) · [MIT license](LICENSE)

README.pypi.md

@@ -45,4 +45,6 @@ Preview AI calls without running the script: `aiython --explain tickets.py`.
 
 [Documentation](https://sunmodza.github.io/aiython-docs/) · [Examples](https://sunmodza.github.io/aiython-docs/examples/) · [Installation](https://sunmodza.github.io/aiython-docs/getting-started/)
 
-Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. MIT licensed.
+Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider.
+
+[Contributing](https://github.com/sunmodza/aiython/blob/main/CONTRIBUTING.md) · MIT licensed.