chore: add design docs and repository files

.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# This file defines the code owners for the repository.
+# Code owners are automatically assigned as reviewers for pull requests.
+
+# Default owner (applies to all files)
+* @lv416e
+
+# Owner of workflow files
+.github/workflows/* @lv416e
+
+# Owner of release-related files
+CHANGELOG.md @lv416e
+pyproject.toml @lv416e

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+A clear and concise description of what the bug is.
+
+## To Reproduce
+Steps to reproduce the behavior:
+1. Install '...'
+2. Run code '...'
+3. See error
+
+## Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## Environment
+
+- OS: [e.g. Ubuntu 20.04, macOS 12.3]
+- Python version: [e.g. 3.10.4]
+- JAX version: [e.g. 0.4.10]
+- GPU model (if applicable): [e.g. NVIDIA RTX 3080]
+- riemannax version: [e.g. 0.1.0]
+
+## Error Logs
+
+```
+- Paste any error messages or stack traces here
+```
+
+## Additional Context
+
+- Add any other context about the problem here.

.github/ISSUE_TEMPLATE/documentation_improvement.md

@@ -0,0 +1,22 @@
+---
+name: Documentation improvement
+about: Suggest improvements to documentation
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Issue
+
+ - Describe what's missing, unclear, or incorrect in the documentation.
+
+## Suggested Improvement
+
+ - A clear and concise description of how the documentation could be improved.
+
+## Page/Section Reference
+
+ - Please provide a link or reference to the specific documentation page or section.
+
+## Additional Context
+ - Add any other context or screenshots about the documentation issue here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+
+ - A clear and concise description of what you want to happen.
+
+## Use Case
+ - Describe the use case or problem this feature would solve.
+
+## Proposed Solution
+
+ - If you have an idea of how to implement this feature, please describe it here.
+
+## Alternatives Considered
+
+ - A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional Context
+
+ - Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+## Description
+
+<!--- Describe your changes in detail -->
+
+## Related Issue
+
+<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
+<!--- Please link to the issue here: -->
+
+Closes #(issue)
+
+## Motivation and Context
+
+<!--- Why is this change required? What problem does it solve? -->
+<!--- If it adds a new feature, describe the use case for the feature -->
+
+## Type of Change
+
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Performance improvement
+
+## How Has This Been Tested?
+
+<!--- Please describe in detail how you tested your changes. -->
+<!--- Include details of your testing environment, and the tests you ran to -->
+<!--- see how your change affects other areas of the code, etc. -->
+
+## Checklist:
+
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+
+- [ ] My code follows the code style of this project
+- [ ] I have updated the documentation accordingly
+- [ ] I have added tests to cover my changes
+- [ ] All new and existing tests passed
+- [ ] I have updated the CHANGELOG.md file with my changes
+- [ ] My change doesn't break existing functionality
+
+## Additional Information
+
+<!--- Any additional information that would be helpful for reviewers -->
+
+-

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "polytopax/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "polytopax/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: |
+            **/requirements*.txt
+            pyproject.toml
+            setup.py
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+          pip install sphinx==7.2.6 sphinx-rtd-theme==2.0.0 nbsphinx==0.9.3 myst-parser==2.0.0
+
+      - name: Build documentation
+        run: |
+          cd docs
+          mkdir -p _static
+          python build_docs.py
+
+      - name: Verify documentation build
+        run: |
+          if [ ! -f docs/_build/html/index.html ]; then
+            echo "Documentation build failed: index.html not found"
+            exit 1
+          fi
+          echo "Documentation build successful"

.github/workflows/lint.yml

@@ -0,0 +1,25 @@
+name: Lint
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Lint with ruff
+        run: |
+          ruff check .

.github/workflows/release.yml

@@ -0,0 +1,166 @@
+name: Release
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  test-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build package
+        run: |
+          python -m build
+      - name: Check package
+        run: |
+          twine check dist/*
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+          attestations: true
+
+  build-and-publish:
+    needs: test-publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build package
+        run: |
+          python -m build
+      - name: Check package
+        run: |
+          twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          attestations: true
+
+  create-release:
+    needs: build-and-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Extract changelog for version
+        id: extract_changelog
+        run: |
+          VERSION=${{ steps.get_version.outputs.VERSION }}
+          # Extract changelog section for this version
+          CHANGELOG_SECTION=$(awk -v ver="$VERSION" '
+            BEGIN { in_section = 0; section = ""; }
+            /^## \[[0-9]+\.[0-9]+\.[0-9]+/ {
+              if (in_section) { exit; }
+              if ($0 ~ ver) { in_section = 1; }
+            }
+            in_section { section = section $0 "\n"; }
+            END { print section; }
+          ' CHANGELOG.md)
+
+          # If no specific version section found, use Unreleased section
+          if [ -z "$CHANGELOG_SECTION" ]; then
+            CHANGELOG_SECTION=$(awk '
+              BEGIN { in_section = 0; section = ""; }
+              /^## \[Unreleased\]/ { in_section = 1; }
+              /^## \[[0-9]+\.[0-9]+\.[0-9]+/ { if (in_section) { exit; } }
+              in_section { section = section $0 "\n"; }
+              END { print section; }
+            ' CHANGELOG.md)
+          fi
+
+          # Save to output, handling multiline strings
+          echo "CHANGELOG_SECTION<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG_SECTION" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Generate release notes
+        id: generate_release_notes
+        uses: mikepenz/release-changelog-builder-action@v4
+        with:
+          configuration: |
+            {
+              "categories": [
+                {
+                  "title": "## 🚀 Features",
+                  "labels": ["feature", "enhancement"]
+                },
+                {
+                  "title": "## 🐛 Fixes",
+                  "labels": ["fix", "bug"]
+                },
+                {
+                  "title": "## 📚 Documentation",
+                  "labels": ["documentation"]
+                },
+                {
+                  "title": "## 🧪 Tests",
+                  "labels": ["test"]
+                },
+                {
+                  "title": "## 🔧 Maintenance",
+                  "labels": ["chore", "dependencies"]
+                }
+              ]
+            }
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: Release v${{ steps.get_version.outputs.VERSION }}
+          body: |
+            # Release v${{ steps.get_version.outputs.VERSION }}
+
+            ## Changelog
+            ${{ steps.extract_changelog.outputs.CHANGELOG_SECTION }}
+
+            ## Pull Requests
+            ${{ steps.generate_release_notes.outputs.changelog }}
+          draft: false
+          prerelease: false
+          files: |
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}