feat: implement python-based repository bootstrapping and modernize documentation

.editorconfig

@@ -1,5 +1,5 @@
 # ==============================================================================
-# EditorConfig for project_name
+# EditorConfig for template-python
 # https://editorconfig.org
 #
 # This file enforces consistent coding styles across multiple editors and IDEs.

.env.example

@@ -15,7 +15,7 @@
 APP_ENV=development
 # Enable/disable debug mode (verbose logging, stack traces)
 APP_DEBUG=true
-APP_NAME="project_name"
+APP_NAME="template_python"
 APP_VERSION="1.0.0"
 # Base URL for the application (useful for generating absolute links, emails)
 APP_URL=http://localhost:8080
@@ -42,13 +42,13 @@ CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080
 DB_CONNECTION=postgres
 DB_HOST=localhost
 DB_PORT=5432
-DB_DATABASE=project_name_dev
+DB_DATABASE=template_python_dev
 DB_USERNAME=admin
 DB_PASSWORD=secret
 # Database schema (if applicable, e.g., public for postgres)
 DB_SCHEMA=public
 # Full connection string alternative (often used by ORMs like Prisma or SQLAlchemy)
-# DATABASE_URL=postgres://admin:secret@localhost:5432/project_name_dev
+# DATABASE_URL=postgres://admin:secret@localhost:5432/template_python_dev
 
 # ------------------------------------------------------------------------------
 # Cache / Key-Value Store / Message Brokers

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,28 +1,28 @@
 ---
 name: 🐛 Bug Report
-description: Create a report to help us improve {{project_name}}
+description: Create a report to help us improve template-python
 labels:
   - "bug"
   - "triage"
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for taking the time to report a bug to `{{project_name}}`!
+        Thanks for taking the time to report a bug to `template-python`!
         > [!IMPORTANT]
         > If you have found a **security vulnerability**, please refer to our [Security Policy](../SECURITY.md) and do not open a public issue.
-        For general help and Q&A, please use [GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions) instead.
+        For general help and Q&A, please use [GitHub Discussions](https://github.com/markurtz/template-python/discussions) instead.
   - type: checkboxes
     id: checks
     attributes:
       label: Search before asking
       description: Please confirm that you have checked the following before submitting your
         bug report.
       options:
-        - label: I have searched the [existing issues](https://github.com/{{organization}}/{{project_name}}/issues)
+        - label: I have searched the [existing issues](https://github.com/markurtz/template-python/issues)
             and could not find a similar bug.
           required: true
-        - label: I have read the [Official Documentation](https://{{organization}}.github.io/{{project_name}}).
+        - label: I have read the [Official Documentation](https://markurtz.github.io/template-python).
           required: true
   - type: textarea
     id: description
@@ -60,7 +60,7 @@ body:
       value: |
         - OS (e.g., Linux, macOS, Windows):
         - Language Version (e.g., Python 3.10):
-        - `{{project_name}}` Version:
+        - `template-python` Version:
         - Other relevant dependency versions:
     validations:
       required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,14 +1,14 @@
 ---
 name: Feature Request
-description: Suggest an idea for {{project_name}}
+description: Suggest an idea for template-python
 labels:
   - "enhancement"
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for taking the time to suggest a feature for {{project_name}}!
-        Before submitting, please ensure you have searched our existing [Issues](https://github.com/{{organization}}/{{project_name}}/issues) and [Discussions](https://github.com/{{organization}}/{{project_name}}/discussions) to see if this feature has already been requested.
+        Thanks for taking the time to suggest a feature for template-python!
+        Before submitting, please ensure you have searched our existing [Issues](https://github.com/markurtz/template-python/issues) and [Discussions](https://github.com/markurtz/template-python/discussions) to see if this feature has already been requested.
   - type: textarea
     id: problem
     attributes:

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,5 @@
 <!--
-Thanks for contributing to {{project_name}}!
+Thanks for contributing to template-python!
 Please review the [Contributing Guidelines](../CONTRIBUTING.md) before submitting your PR.
 -->
 
@@ -16,11 +16,11 @@ If this PR introduces a new feature or changes existing behavior, describe the c
 
 <!-- Please check the box(es) that apply to this PR. -->
 
-- [ ] 🐛 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 not work as expected)
-- [ ] 📝 Documentation update (changes to `README.md`, `SUPPORT.md`, docstrings, etc.)
-- [ ] 🛠️ Maintenance/Refactoring (non-breaking change that improves code structure or quality)
+- [ ] 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 not work as expected)
+- [ ] Documentation update (changes to `README.md`, `SUPPORT.md`, docstrings, etc.)
+- [ ] Maintenance/Refactoring (non-breaking change that improves code structure or quality)
 
 ## Test Plan
 
@@ -52,16 +52,16 @@ please add screenshots, terminal output, or recordings to demonstrate the change
 
 - [ ] Includes AI-assisted code completion
 - [ ] Includes code generated by an AI application
-- [ ] Includes AI-generated tests (NOTE: AI written tests should have a docstring that includes `## WRITTEN BY AI ##`)
+- [ ] Includes AI-generated tests
 
 ## Checklist
 
 > [!IMPORTANT]
-> Please review and complete this checklist before submitting your PR. This helps our maintainers process your contribution faster and ensures it meets the quality standards of `{{project_name}}`.
+> Please review and complete this checklist before submitting your PR. This helps our maintainers process your contribution faster and ensures it meets the quality standards of `template-python`.
 
 - [ ] "I certify that all code in this PR is my own, except as noted below."
 - [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guide.
-- [ ] My code follows the established style guidelines of `{{project_name}}`.
+- [ ] My code follows the established style guidelines of `template-python`.
 - [ ] I have performed a self-review of my own code.
 - [ ] I have commented my code, particularly in hard-to-understand areas.
 - [ ] I have made corresponding changes to the documentation.

.github/workflows/development.yml

@@ -75,7 +75,9 @@ jobs:
   # ── Stage 3: Docs (Conditional) ────────────────────────────────────────────
   docs:
     name: "Build & Deploy Docs"
-    needs: changes
+    needs:
+      - changes
+      - tests
     if: needs.changes.outputs.docs == 'true' && github.event.pull_request.head.repo.fork ==
       false
     uses: ./.github/workflows/_docs.yml

.github/workflows/main.yml

@@ -52,7 +52,9 @@ jobs:
   # ── Stage 3: Documentation ─────────────────────────────────────────────────
   docs:
     name: "Build & Deploy Docs"
-    needs: quality
+    needs:
+      - quality
+      - tests
     uses: ./.github/workflows/_docs.yml
     with:
       build_type: "dev"

.github/workflows/nightly.yml

@@ -81,7 +81,9 @@ jobs:
   # ── Stage 4: Alpha Docs ────────────────────────────────────────────────────
   docs:
     name: "Nightly Docs"
-    needs: check-changes
+    needs:
+      - check-changes
+      - test
     if: needs.check-changes.outputs.has_changes == 'true'
     uses: ./.github/workflows/_docs.yml
     with:
@@ -121,8 +123,7 @@ jobs:
         uses: actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2  # v1.5.1
         with:
           subject-path: dist/*
-      - name: Publish to PyPI
-        if: github.repository_id != 1226495532  # Skip PyPI for the template repo itself
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14
-        with:
-          packages-dir: dist/
+#       - name: Publish to PyPI
+#         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14
+#         with:
+#           packages-dir: dist/

.github/workflows/release.yml

@@ -49,6 +49,7 @@ jobs:
   # ── Stage 4: Versioned Docs ────────────────────────────────────────────────
   docs:
     name: "Versioned Docs"
+    needs: test
     uses: ./.github/workflows/_docs.yml
     with:
       build_type: "release"
@@ -82,11 +83,10 @@ jobs:
         uses: actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2  # v1.5.1
         with:
           subject-path: dist/*
-      - name: Publish to PyPI
-        if: github.repository_id != 1226495532  # Skip PyPI for the template repo itself
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14
-        with:
-          packages-dir: dist/
+#       - name: Publish to PyPI
+#         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14
+#         with:
+#           packages-dir: dist/
       - name: Create GitHub Release
         if: ${{ github.ref_type == 'tag' }}
         uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191  # v2.0.8

.gitignore

@@ -161,7 +161,7 @@ nosetests.xml
 # ==============================================================================
 
 # Python
-src/project_name/version.py
+src/template_python/version.py
 __pycache__/
 *.py[cod]
 *$py.class

AGENTS.md

@@ -5,7 +5,7 @@
 
 ## Project Context
 
-**`project_name`** is a production-ready Apache 2.0 template repository for bootstrapping modern software projects.
+**`template-python`** is a production-ready Apache 2.0 template repository for bootstrapping modern software projects.
 **Primary language:** `Python 3.10+`\
 **Package manager:** `Hatch`
 
@@ -54,7 +54,7 @@
 
 - **`docs/`** and **`mkdocs.yml`** control the site. Do not create docs outside the `nav:` tree.
 - `docs/index.md` dynamically includes `README.md` via MkDocs snippets.
-- Use `{{placeholder}}` variables for templated fields (e.g., `project_name`, `{{organization}}`).
+- Use `{{placeholder}}` variables for templated fields (e.g., `template-python`, `markurtz`).
 
 ## Agent Notes
 

CITATION.cff

@@ -3,20 +3,19 @@
 # For more information on the CFF format, see: https://citation-file-format.github.io/
 
 cff-version: 1.2.0
-title: "project_name"
+title: "template-python"
 message: "If you use this software, please cite it as below."
 type: software
-version: "{{version}}"
 date-released: "{{date_released}}"
 license: Apache-2.0
 
 # You can list individual authors or an organization.
 # This defaults to the organization to match the README's BibTeX.
 authors:
-  - name: "{{organization}}"
+  - name: "markurtz"
 #  - family-names: "{{author_family_name}}"
 #    given-names: "{{author_given_name}}"
 #    orcid: "https://orcid.org/{{orcid}}"
 
-repository-code: "https://github.com/{{organization}}/project_name"
-url: "https://{{organization}}.github.io/project_name"
+repository-code: "https://github.com/markurtz/template-python"
+url: "https://markurtz.github.io/template-python"

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# Code of Conduct for `project_name`
+# Code of Conduct for `template-python`
 
 ## Our Pledge
 
@@ -61,7 +61,8 @@ representative at an online or offline event.
 > [!IMPORTANT]
 > Instances of abusive, harassing, or otherwise unacceptable behavior may be
 > reported to the community leaders responsible for enforcement by contacting
-> **conduct@{{organization}}.com**.
+>
+> <!-- conduct@example.com -->
 
 All complaints will be reviewed and investigated promptly and fairly.
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to project_name
+# Contributing to template-python
 
-First off, thank you for considering contributing to `project_name`! It's people like you that make this project great.
+First off, thank you for considering contributing to `template-python`! It's people like you that make this project great.
 
 ## Code of Conduct
 
@@ -15,13 +15,13 @@ If you discover a security issue, please refer to our [Security Policy](SECURITY
 
 ## How Can I Contribute?
 
-There are many ways to contribute to `project_name`, and not all of them involve writing code:
+There are many ways to contribute to `template-python`, and not all of them involve writing code:
 
 - **Reporting Bugs:** Help us improve by submitting detailed bug reports via our issue tracker.
 - **Suggesting Features:** Propose new features or enhancements that could benefit the project.
 - **Improving Documentation:** Fix typos, add examples, or write new guides.
 - **Writing Code:** Fix bugs, implement features, or improve performance.
-- **Helping Others:** Answer questions in [Discussions](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/discussions) or issue comments.
+- **Helping Others:** Answer questions in [Discussions](https://github.com/markurtz/template-python/discussions) or issue comments.
 
 For general questions and help, please see [SUPPORT.md](SUPPORT.md).
 
@@ -45,7 +45,7 @@ Before you start coding, please refer to our [Development Guide](DEVELOPING.md)
 
 ### 3. Making Changes
 
-1. **Fork the Repository:** Fork the `project_name` repository to your GitHub account.
+1. **Fork the Repository:** Fork the `template-python` repository to your GitHub account.
 1. **Create a Branch:** Create a new branch from `main` for your work (e.g., `git checkout -b feat/add-new-feature`).
 1. **Write Code:** Implement your changes, adhering to the project's coding standards.
 1. **Write Tests:** Add unit tests or integration tests for your changes to ensure stability.
@@ -67,4 +67,4 @@ Before you start coding, please refer to our [Development Guide](DEVELOPING.md)
 
 ## Licensing
 
-By contributing to `project_name`, you agree that your contributions will be licensed under its [Apache 2.0 License](LICENSE).
+By contributing to `template-python`, you agree that your contributions will be licensed under its [Apache 2.0 License](LICENSE).

DEVELOPING.md

@@ -1,4 +1,4 @@
-# Developing `project_name`
+# Developing `template-python`
 
 This guide provides instructions for setting up your development environment, navigating the project structure, and adhering to our coding standards.
 
@@ -22,8 +22,8 @@ Ensure your system meets the following requirements before getting started:
 > Once implemented, you can spin up the development environment with:
 >
 > ```bash
-> git clone https://github.com/{{organization}}/project_name.git
-> cd project_name
+> git clone https://github.com/markurtz/template-python.git
+> cd template-python
 >
 > # Build and start the development environment in the background
 > docker-compose up -d --build

Dockerfile

@@ -1,5 +1,5 @@
 # ---------------------------------------------------------
-# project_name Dockerfile
+# template-python Dockerfile
 # Licensed under the Apache License, Version 2.0
 # ---------------------------------------------------------
 # Standardized Multi-stage Dockerfile Template for Python
@@ -23,7 +23,7 @@ RUN pip install uv hatch
 # Copy package manifests and install dependencies
 COPY pyproject.toml README.md ./
 # Create a dummy src directory to satisfy hatch build if needed
-RUN mkdir -p src/project_name && touch src/project_name/__init__.py
+RUN mkdir -p src/template_python && touch src/template_python/__init__.py
 RUN uv pip install --system --no-cache -e .
 
 # Copy application source code
@@ -40,10 +40,10 @@ RUN hatch build
 FROM python:3.10-slim
 
 # OCI Standard Labels
-LABEL org.opencontainers.image.title="project_name"
+LABEL org.opencontainers.image.title="template-python"
 LABEL org.opencontainers.image.description="Production-ready Python application container"
 LABEL org.opencontainers.image.licenses="Apache-2.0"
-LABEL org.opencontainers.image.source="https://github.com/{{organization}}/project_name"
+LABEL org.opencontainers.image.source="https://github.com/markurtz/template-python"
 
 # Define environment variables
 ENV APP_ENV=production \
@@ -68,4 +68,4 @@ USER appuser
 EXPOSE 8080
 
 # Define the command to run the application
-CMD ["python", "-m", "project_name"]
+CMD ["python", "-m", "template_python"]

NOTICE

@@ -1,8 +1,8 @@
-project_name
-Copyright {{year}} {{organization}}
+template-python
+Copyright {{year}} markurtz
 
-This product includes software developed by {{organization}}
-(https://github.com/{{organization}}/project_name).
+This product includes software developed by markurtz
+(https://github.com/markurtz/template-python).
 
 =========================================================================
 Third-Party Attributions