Improve issue and PR categories

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug report
+description: Report reproducible behavior that is incorrect or unexpected.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Search existing issues before reporting a bug. Do not report security
+        vulnerabilities here; follow the instructions in SECURITY.md instead.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the incorrect behavior and its impact.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: How can we reproduce it?
+      description: Provide the smallest reliable example and exact steps.
+      placeholder: |
+        1. Install ...
+        2. Run ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the package version or commit, Python version, and operating system.
+      placeholder: |
+        Package version or commit:
+        Python version:
+        Operating system:
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add logs, tracebacks, screenshots, or other useful details.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched for an existing issue that describes this problem.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,35 @@
+name: Documentation improvement
+description: Report missing, unclear, or incorrect documentation.
+title: "[Docs]: "
+labels:
+  - documentation
+body:
+  - type: input
+    id: location
+    attributes:
+      label: Where is the documentation problem?
+      description: Link to the page or name the file and section.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What needs improvement?
+      description: Explain what is missing, unclear, or incorrect.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested change
+      description: Describe or draft the improvement if you have one.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked the current documentation and existing issues.
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,53 @@
+name: Feature request
+description: Suggest a new capability or an improvement to existing behavior.
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Start with the user need rather than a specific implementation.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Explain who has the problem and why the current behavior is insufficient.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+      description: Describe the desired behavior.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What alternatives have you considered?
+      description: Include current workarounds when applicable.
+
+  - type: textarea
+    id: success
+    attributes:
+      label: How will we know this is complete?
+      description: List the outcomes or acceptance criteria that matter.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched for an existing request that covers this idea.
+          required: true

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,35 @@
+name: Question
+description: Ask for help when the documentation does not answer your question.
+title: "[Question]: "
+labels:
+  - question
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: What do you need help with?
+      description: Ask a specific question and describe what you are trying to accomplish.
+    validations:
+      required: true
+
+  - type: textarea
+    id: attempted
+    attributes:
+      label: What have you tried?
+      description: Include relevant documentation, code, commands, or error messages.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include version and platform details when relevant.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched the documentation and existing issues first.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,16 +2,33 @@
 
 Describe the user-facing problem and the change that addresses it.
 
-## Acceptance Criteria
+## Related Issue
 
-- [ ] The behavior matches the issue or request.
-- [ ] Relevant edge cases are covered.
+Link the issue this change addresses, such as `Closes #123`.
+
+## Category
+
+Select one primary category.
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Documentation
+- [ ] Maintenance or refactor
+- [ ] Dependency update
+
+## Compatibility
+
+- [ ] This change is backward compatible.
+- [ ] This change deprecates existing behavior.
+- [ ] This change breaks existing behavior.
 
 ## Validation
 
 List the commands run and their results.
 
-## Documentation and Release Notes
+## Checklist
 
+- [ ] Tests cover the change, or no new tests are needed.
+- [ ] Relevant edge cases are covered.
 - [ ] Documentation is updated, or no update is needed.
 - [ ] `CHANGELOG.md` is updated for a user-facing, compatibility, or security change.

.gitignore

@@ -1,5 +1,6 @@
 # AI stuff
 .claude
+.goals
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

AGENTS.md

@@ -49,8 +49,13 @@ configure an AWS OIDC role with `DOCS_AWS_ROLE_ARN` and `DOCS_AWS_REGION`, and
 set the `DOCS_DEPLOY_ENABLED` repository variable to `true`.
 
 When instantiating the template, replace the distribution placeholder in
-`docs/conf.py`, set the Palewire theme canonical and base URLs, and add an API
-reference page using autosummary for the package's public modules. Add
+`docs/conf.py`, set `html_baseurl` to the production documentation URL, and
+add an API reference page using autosummary for the package's public modules.
+The `palewire` extension derives the canonical theme URL from `html_baseurl`
+and provides the `wide` layout and `sidebar` navigation presets; adjust those
+settings only when the project needs a different presentation. For a brand-new,
+simpler documentation project, `uvx sphinx-palewire-theme init` is an optional
+shortcut, not a replacement for this template's richer configuration. Add
 host-specific linkcheck exclusions only for documented, reproducibly unstable
 URLs.
 

CHANGELOG.md

@@ -16,6 +16,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Security
 
+## [2.1.1] - 2026-08-25
+
+### Added
+
+### Changed
+
+- Enable the Palewire Sphinx extension defaults in the template and document
+  its `html_baseurl` configuration ([#278]).
+
+### Fixed
+
+### Removed
+
+### Security
+
 ## [2.1.0] - 2026-08-23
 
 ### Added
@@ -44,7 +59,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Security
 
-[Unreleased]: https://github.com/palewire/python-open-source-template/compare/2.1.0...HEAD
+[Unreleased]: https://github.com/palewire/python-open-source-template/compare/2.1.1...HEAD
+[2.1.1]: https://github.com/palewire/python-open-source-template/compare/2.1.0...2.1.1
 [2.1.0]: https://github.com/palewire/python-open-source-template/compare/2.0.0...2.1.0
 [#261]: https://github.com/palewire/python-open-source-template/pull/261
 [#262]: https://github.com/palewire/python-open-source-template/pull/262
@@ -59,3 +75,4 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 [#271]: https://github.com/palewire/python-open-source-template/pull/271
 [#272]: https://github.com/palewire/python-open-source-template/pull/272
 [#273]: https://github.com/palewire/python-open-source-template/pull/273
+[#278]: https://github.com/palewire/python-open-source-template/pull/278

TEMPLATE_SETUP.md

@@ -11,7 +11,10 @@ Complete this checklist before the first release.
 
 ## Documentation
 
-- [ ] Replace the distribution placeholder and production URLs in `docs/conf.py`.
+- [ ] Replace the distribution placeholder and set `html_baseurl` to the
+      production documentation URL in `docs/conf.py`. The `palewire` extension
+      derives the canonical theme URL from it and provides the `wide` layout and
+      `sidebar` navigation presets, which you can adjust for the project.
 - [ ] Add an autosummary-based API reference for public modules.
 - [ ] Configure S3 deployment through the protected `docs-production`
       environment, AWS OIDC variables, and `DOCS_DEPLOY_ENABLED=true`.

docs/conf.py

@@ -19,6 +19,7 @@
 pygments_style = "sphinx"
 
 extensions = [
+    "palewire",
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -48,6 +49,8 @@
 linkcheck_retries = 2
 
 html_theme = "palewire"
-# Set these after choosing the production documentation URL:
-# html_theme_options = {"canonical_url": "https://docs.example.com/"}
+# Set this after choosing the production documentation URL. The Palewire extension
+# derives the theme canonical URL from html_baseurl.
 # html_baseurl = "https://docs.example.com/"
+palewire_layout = "wide"
+palewire_navigation = "sidebar"

pyproject.toml

@@ -67,7 +67,7 @@ docs = [
     "sphinxcontrib-mermaid",
     "sphinx_copybutton",
     "myst-parser",
-    "sphinx-palewire-theme",
+    "sphinx-palewire-theme>=0.1.8",
 ]
 notebooks = [
     "jupyterlab",