feat: refresh template observability and agent defaults

Remove Logfire, add optional Sentry and base app exceptions, and update the template docs and config defaults to match the current startup flow.

Co-Authored-By: greg-agent[bot] <305014151+greg-agent[bot]@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.env.dev

@@ -0,0 +1,5 @@
+ENVIRONMENT=development
+
+# Optional: leave empty to disable Sentry
+SENTRY_DSN=
+SENTRY_TRACES_SAMPLE_RATE=0.1

.env.example

@@ -0,0 +1,29 @@
+# Dependabot keeps base images and dependencies current so the Trivy CVE gate
+# stays actionable (the fix for a flagged CVE is almost always a version bump).
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"
+    open-pull-requests-limit: 5
+    groups:
+      python-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"
+    open-pull-requests-limit: 3
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"
+    open-pull-requests-limit: 3

.github/dependabot.yml

@@ -0,0 +1,140 @@
+This file provides guidance to AI coding agents working with this repository.
+
+## Project Overview
+
+This repository is a reusable Python project template. It is intentionally small
+and generic, so changes should prefer simple, composable patterns over
+project-specific architecture.
+
+The current template includes:
+
+- Poetry for dependency management
+- Pydantic Settings for configuration
+- Loguru for logging
+- Optional Sentry initialization
+- Custom application exceptions
+- pytest, Ruff, isort, and mypy
+- Docker and GitHub Actions
+
+When adapting this template for a real project, preserve the clean foundation
+and add framework- or domain-specific code incrementally.
+
+## Common Development Commands
+
+```bash
+make deps      # Install dependencies
+make format    # Format code
+make lint      # Run Ruff, isort, and mypy
+make test      # Run tests
+make ci-test   # Run tests with coverage
+make dev       # Run the example entrypoint
+```
+
+## Core Principles
+
+### Keep the template generic
+
+- Do not introduce business-specific naming, copy, or architecture into the
+  template.
+- Prefer framework-agnostic utilities in `src/core/` unless the repository has
+  clearly become tied to a framework.
+- New defaults should be broadly useful to future projects, not tailored to one
+  app.
+
+### Favor minimal, explicit patterns
+
+- Prefer small modules with obvious responsibilities.
+- Avoid clever abstractions unless they clearly reduce repeated complexity.
+- Keep startup wiring easy to trace from `src/main.py`.
+- Make optional integrations truly optional by gating them with settings.
+
+### Preserve clean layering
+
+- `src/core/` is for reusable foundation code: config, logging, observability,
+  exceptions, enums, and similar cross-cutting concerns.
+- `src/main.py` is the composition root for startup wiring and top-level error
+  handling.
+- `tests/` should verify behavior, not implementation details.
+
+## Configuration Conventions
+
+- All configuration should live in `src/core/config.py`.
+- Environment variables should be documented in `.env.example`.
+- Copy `.env.example` to `.env` for local development; never commit secrets.
+- Optional services must degrade cleanly when their config is absent.
+
+Examples in this template:
+
+- Sentry is disabled when `SENTRY_DSN` is empty.
+- Logging configuration is environment-aware via `ENVIRONMENT`.
+
+## Logging, Observability, and Errors
+
+- Use `src/core/logging.py` for Loguru setup.
+- Keep observability integrations minimal in the template. Add advanced routing,
+  filtering, or framework-specific integrations only in downstream projects.
+- Use custom exceptions from `src/core/exceptions/` for intentional app-level
+  failures.
+- Catch custom app exceptions at the top level in `src/main.py` or the
+  framework-specific entrypoint, log them consistently, and exit or translate
+  them there.
+
+## Dependencies
+
+- Use Poetry for all dependency changes.
+- Keep runtime dependencies minimal.
+- Add a dependency to the template only if it is broadly useful across many new
+  projects.
+- Remove stale dependencies when their integration is removed from the codebase.
+
+## Testing and Verification
+
+- Add or update focused tests for behavior changes.
+- Prefer test-first changes for new features and bug fixes.
+- After substantive edits, run:
+
+```bash
+make test
+make lint
+```
+
+- If config, startup wiring, or dependency behavior changes, add tests for the
+  new edge cases.
+
+## Code Style
+
+- Python 3.13 target.
+- Line length: 100.
+- Type hints are required for public function signatures.
+- Keep comments focused on why, not what.
+- Public modules and public classes should have useful docstrings.
+- Avoid commented-out code.
+
+## Template-Specific Change Guidelines
+
+- If you add a new core capability, wire it through all relevant template entry
+  points:
+  - dependencies in `pyproject.toml`
+  - environment variables in `.env.example`
+  - startup/config code in `src/core/` or `src/main.py`
+  - tests in `tests/`
+  - docs in `README.md` if the capability affects setup or usage
+
+- If you rename or remove a template feature, clean up:
+  - stale tests
+  - stale README references
+  - stale environment variables
+  - stale dependencies and lockfile entries
+
+## What Not to Do
+
+- Do not hardcode secrets or commit real credentials.
+- Do not add service-specific architecture to the template without a clear need.
+- Do not leave dead examples, mismatched tests, or outdated docs behind.
+- Do not couple the template to a framework unless that is an intentional
+  direction change for the repository.
+
+## Keeping This File in Sync
+
+Update this file whenever the template's development workflow, architectural
+expectations, or core building blocks change.

AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -1,6 +1,6 @@
-# Template for python repositories.
-[![Lint](https://github.com/axioma-ai-labs/python-template/actions/workflows/ci-lint.yml/badge.svg)](https://github.com/axioma-ai-labs/python-template/actions/workflows/ci-lint.yml)
-[![Docker](https://github.com/axioma-ai-labs/python-template/actions/workflows/docker.yml/badge.svg)](https://github.com/axioma-ai-labs/python-template/actions/workflows/docker.yml)
+# Template for Python repositories
+[![CI](https://github.com/axioma-ai-labs/python-template/actions/workflows/main.yml/badge.svg)](https://github.com/axioma-ai-labs/python-template/actions/workflows/main.yml)
+[![Docker](https://github.com/axioma-ai-labs/python-template/actions/workflows/docker-latest.yml/badge.svg)](https://github.com/axioma-ai-labs/python-template/actions/workflows/docker-latest.yml)
 
 ## Table of Contents
 
@@ -10,11 +10,11 @@
 
 ## Overview
 
-This project is a template for Python repositories. It includes a Makefile with commands for 
-formatting, linting, and installing dependencies. It also includes a pre-configured Github Actions 
+This project is a template for Python repositories. It includes a Makefile with commands for
+formatting, linting, and installing dependencies. It also includes pre-configured GitHub Actions
 workflow for CI/CD.
 
-Let the following note be in your project-specific Readme file:
+You can add the following note to a project-specific README:
 
 > [!NOTE]
 > This project uses the [python-template](https://github.com/axioma-ai-labs/python-template)
@@ -26,24 +26,30 @@ Let the following note be in your project-specific Readme file:
 The project uses Pyenv for managing Python versions and Poetry for managing dependencies. Find more
 details in the [Development](#development) section.
 
-### 2. Pydantic
+### 2. Pydantic, Loguru, and optional Sentry
 
-The project uses `Pydantic` for data validation and settings management.
+The project uses `Pydantic` for data validation and settings management, `Loguru` for logging,
+and optional `Sentry` initialization for error tracking and performance monitoring.
 
-### 3. Ruff, Isort, Mypy
+### 3. Custom application exceptions
 
-The project uses `Ruff` for formatting, `Isort` for sorting imports, and `Mypy` for static typing. 
-Recommended to use with `Makefile` commands. For more information look at the 
+The template includes reusable application exceptions in `src/core/exceptions/` and a top-level
+entrypoint wrapper in `src/main.py` for consistent error handling.
+
+### 4. Ruff, isort, mypy, and pytest
+
+The project uses `Ruff` for formatting, `isort` for sorting imports, `mypy` for static typing,
+and `pytest` for testing. Recommended to use with `Makefile` commands. For more information look at the
 [Makefile](./Makefile).
 
-### 4. Github Actions
+### 5. GitHub Actions and Dependabot
 
-The project uses Github Actions for CI/CD. Look at the [.github/workflows](.github/workflows) for 
-more information. The package includes the linting workflow per default.
+The project uses GitHub Actions for CI/CD and includes Dependabot configuration for Python,
+Docker, and GitHub Actions updates.
 
-### 5. Makefile
+### 6. Makefile
 
-The project uses Makefile for automating tasks. Look at the [Makefile](./Makefile) for more 
+The project uses Makefile for automating tasks. Look at the [Makefile](./Makefile) for more
 information.
 
 The provided Makefile includes the following commands:
@@ -52,6 +58,7 @@ The provided Makefile includes the following commands:
 make deps    # Install dependencies
 make format  # Format code
 make lint    # Lint code
+make test    # Run tests
 ```
 
 ## Development
@@ -60,13 +67,13 @@ make lint    # Lint code
 
 #### Overview
 
-You will need to have Python 3.13 and Poetry installed. The next step is to checkout the repository 
-and install the Python dependencies. Then, you will be able to utilize the CLI and run the tests. 
+You will need to have Python 3.13 and Poetry installed. The next step is to checkout the repository
+and install the Python dependencies. Then, you will be able to run the example entrypoint and tests.
 The following assumes a Debian/Ubuntu machine; your mileage may vary.
 
 #### Prerequisites
 
-You can use pyenv for getting a specific python version. Once you have pyenv installed, you can 
+You can use pyenv for getting a specific Python version. Once you have pyenv installed, you can
 install a specific python version:
 
 ```
@@ -101,12 +108,20 @@ poetry add --group dev <package>
 
 #### Setup Environment Variables
 
-You can use the provided `.env.example` file to setup the environment variables. 
+You can use the provided `.env.example` file to set up the environment variables.
 
 ```
 cp .env.example .env
 ```
 
+The default template variables are:
+
+```env
+ENVIRONMENT=development
+SENTRY_DSN=
+SENTRY_TRACES_SAMPLE_RATE=0.1
+```
+
 ### 6. Docker
 
 The project uses Docker for building the image. Look at the [Dockerfile](./Dockerfile) for more 
@@ -116,15 +131,31 @@ information.
 docker build -t python-template .
 ```
 
-### 7. Testing
+### 7. Running the template
+
+Run the example entrypoint:
+
+```bash
+make dev
+```
+
+The startup sequence configures logging, initializes Sentry when `SENTRY_DSN` is set, and then
+runs the example application entrypoint.
+
+### 8. Testing
 
 The project uses pytest for testing. Look at the [Makefile](./Makefile) for more information.
 
 ```
 make test
 ```
 
-### 8. CI/CD
+### 9. AI agent guidance
+
+This repository includes `AGENTS.md` for coding-agent instructions. `CLAUDE.md` points to the same
+content so both entry points stay in sync.
+
+### 10. CI/CD
 
-The project uses Github Actions for CI/CD. Look at the [.github/workflows](.github/workflows) for 
-more information. The package includes the linting and docker build workflows per default.
+The project uses GitHub Actions for CI/CD. Look at the [.github/workflows](.github/workflows) for
+more information. The package includes test/lint and Docker workflows by default.