Improve repo health and release workflow

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @IgnazioDS

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report a reproducible defect in the starter
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug.
+        Please include enough detail for someone else to reproduce it.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the bug and the expected behavior.
+      placeholder: The API returned..., but I expected...
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Include commands, requests, or configuration details.
+      placeholder: |
+        1. Run ...
+        2. Send ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, database setup, and any relevant env vars.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or stack traces
+      description: Paste any relevant output.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/IgnazioDS/langgraph-fastapi-starter/security
+    about: Report vulnerabilities privately through GitHub Security Advisories.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Propose an improvement to the starter
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What is missing or painful today?
+      placeholder: I want to use this starter for..., but...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Describe the smallest useful improvement.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Optional. Describe workarounds or other approaches.

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+- What changed?
+- Why does it matter?
+
+## Verification
+
+- [ ] `make lint`
+- [ ] `make typecheck`
+- [ ] `make test`
+
+## Notes
+
+- Follow-up work
+- Deployment or migration impact

.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distribution artifacts
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+This repository is meant to be forked, customized, and improved in the open.
+Small, focused pull requests are easier to review and more likely to merge.
+
+## Development Setup
+
+1. Create a virtual environment.
+2. Install dependencies with `pip install -e ".[dev]"`.
+3. Copy `.env.example` to `.env`.
+4. Start PostgreSQL with `make up`.
+5. Run migrations with `make migrate`.
+
+## Recommended Workflow
+
+1. Create a branch from `main`.
+2. Make one logical change at a time.
+3. Run `make lint`, `make typecheck`, and `make test`.
+4. Update docs or examples if behavior changed.
+5. Open a pull request with a clear summary and verification notes.
+
+## Pull Request Expectations
+
+- Keep PRs narrow in scope.
+- Describe the user-visible or maintainer-visible impact.
+- Include the commands you ran locally.
+- Call out follow-up work instead of mixing it into the same PR.
+
+## Good First Contributions
+
+- Documentation fixes and walkthrough improvements
+- Additional tests around router, service, or graph behavior
+- Production hardening and deployment guidance
+- Example agent improvements that keep the starter generic
+
+## Reporting Problems
+
+Open an issue with:
+
+- What you expected
+- What actually happened
+- Steps to reproduce
+- Environment details that matter
+
+Security-sensitive issues should follow [SECURITY.md](./SECURITY.md).

Makefile

@@ -1,4 +1,4 @@
-.PHONY: up down dev build install migrate create-key revoke-key test test-verbose lint typecheck clean format help
+.PHONY: venv up down dev build install install-uv migrate create-key revoke-key test test-verbose lint typecheck clean format help
 
 APP_NAME = langgraph-fastapi-starter
 PYTHON = python3
@@ -7,6 +7,10 @@ help: ## Show available targets
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-18s\033[0m %s\n", $$1, $$2}'
 
+venv: ## Create a local virtual environment in .venv
+	@echo "→ Creating virtual environment..."
+	$(PYTHON) -m venv .venv
+
 up: ## Start postgres via Docker Compose
 	@echo "→ Starting database..."
 	docker compose up -d
@@ -20,7 +24,11 @@ down: ## Stop and remove containers
 
 install: ## Install package in editable mode with dev dependencies
 	@echo "→ Installing dependencies..."
-	pip install -e ".[dev]"
+	$(PYTHON) -m pip install -e ".[dev]"
+
+install-uv: ## Install dev dependencies with uv into the selected Python environment
+	@echo "→ Installing dependencies with uv..."
+	uv pip install --python $(PYTHON) -e ".[dev]"
 
 migrate: ## Run database migrations
 	@echo "→ Running migrations..."

README.md

@@ -24,6 +24,14 @@ The full walkthrough lives in [docs/build-your-first-agent.md](./docs/build-your
 
 ---
 
+## Community Health
+
+If you want to contribute, start with [CONTRIBUTING.md](./CONTRIBUTING.md).
+If you need to report a vulnerability, follow [SECURITY.md](./SECURITY.md).
+If you are cutting a tag, follow [docs/releasing.md](./docs/releasing.md).
+
+---
+
 ## Architecture
 
 ```mermaid
@@ -72,21 +80,26 @@ feature flags, admin UI. Add what your product needs. Don't pay for what it does
 git clone https://github.com/IgnazioDS/langgraph-fastapi-starter
 cd langgraph-fastapi-starter
 
-# 2. Configure
+# 2. Create a virtual environment and install dependencies
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+
+# 3. Configure
 cp .env.example .env
 # Set OPENAI_API_KEY and POSTGRES_PASSWORD in .env — everything else has defaults
 
-# 3. Start the database
+# 4. Start the database
 make up
 
-# 4. Run migrations and create your first API key
+# 5. Run migrations and create your first API key
 make migrate
 make create-key NAME="local-dev"
 
-# 5. Run the server
+# 6. Run the server
 make dev
 
-# 6. Verify
+# 7. Verify
 curl -H "Authorization: Bearer <key-from-step-4>" http://localhost:8000/health
 ```
 
@@ -99,6 +112,9 @@ curl -X POST http://localhost:8000/v1/agent/run \
   -d '{"session_id": "demo-1", "message": "What is retrieval-augmented generation?"}'
 ```
 
+If you prefer `uv`, create the environment with `uv venv --python 3.11` and install
+dependencies with `make install-uv`.
+
 ---
 
 ## Build Your Own Agent

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+If you discover a vulnerability, do not open a public issue with exploit details.
+
+## Reporting
+
+Please report security issues privately through GitHub Security Advisories or by
+contacting the repository owner directly through GitHub.
+
+Include:
+
+- A clear description of the issue
+- Impact and affected components
+- Reproduction steps or proof of concept
+- Any suggested remediation
+
+## Scope
+
+Security reports are especially helpful for:
+
+- Authentication and authorization flaws
+- Secrets handling issues
+- Dependency risks with practical impact
+- Injection, deserialization, or unsafe tool execution paths
+- Data exposure through logs, persistence, or API responses
+
+## Response Goals
+
+Best effort:
+
+- Acknowledge receipt quickly
+- Reproduce and assess impact
+- Prepare a fix and coordinated disclosure plan

docs/releasing.md

@@ -0,0 +1,35 @@
+# Releasing
+
+This repository is versioned manually on purpose. The goal is a simple release
+path that keeps source, tags, and release notes in sync without introducing a
+second layer of automation.
+
+## Release Checklist
+
+1. Run `make lint`, `make typecheck`, and `make test`.
+2. Confirm `README.md` and docs match the current setup flow.
+3. Bump the version in `pyproject.toml` and `app/main.py` if behavior changed.
+4. Commit the release changes.
+5. Create a tag such as `v0.2.0`.
+6. Push the branch and tag to GitHub.
+
+```bash
+git tag v0.2.0
+git push origin main --follow-tags
+```
+
+## What Happens On Tag Push
+
+The `Release` GitHub Actions workflow:
+
+- builds the source distribution and wheel
+- creates a GitHub release for the tag
+- attaches the built artifacts to the release
+
+## Versioning Guidance
+
+Use pragmatic semver:
+
+- patch: docs fixes, small bug fixes, non-breaking maintenance
+- minor: new starter capabilities or meaningful extension points
+- major: breaking API or setup changes