docs: add PR/issue templates, CODEOWNERS, CONTRIBUTING

.github/CODEOWNERS

@@ -1,12 +1,22 @@
-# Code owners: auto-assign reviewers for pull requests.
-# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+# CODEOWNERS — default review ownership
+# badhope is the sole owner; replace with team handles in a
+# multi-maintainer setup.
 
-# Default owner for everything in the repo.
+# Default: everything
 *       @badhope
 
-# Security-sensitive files get an explicit owner reminder.
-/SECURITY.md         @badhope
-/.github/workflows/  @badhope
-/.gitleaks.toml      @badhope
-/.github/dependabot.yml @badhope
-/CODEOWNERS          @badhope
+# GitHub configuration
+/.github/        @badhope
+
+# Documentation
+/docs/           @badhope
+/README.md       @badhope
+/CHANGELOG.md    @badhope
+
+# Build / release config
+/package.json    @badhope
+/uv.lock         @badhope
+/package-lock.json @badhope
+/pnpm-lock.yaml  @badhope
+/Cargo.toml      @badhope
+/Cargo.lock      @badhope

.github/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for your interest in contributing! This document covers the
+ground rules so your PR can land quickly and cleanly.
+
+## Branch & PR workflow
+
+> **Direct pushes to `main` are blocked by branch protection.**
+
+1. **Fork** (or create a feature branch if you have write access).
+2. **Branch off `main`**: `git switch -c feat/short-description`
+3. **Make focused commits** following
+   [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat: …`        — new feature
+   - `fix: …`         — bug fix
+   - `refactor: …`    — no behaviour change
+   - `docs: …`        — documentation only
+   - `chore(deps): …` — dependency bumps
+   - `security: …`    — security fix
+4. **Push your branch**: `git push -u origin feat/short-description`
+5. **Open a Pull Request** against `main`. Fill in the PR template.
+6. **Wait for CI** (gitleaks + CodeQL on every repo that has code).
+7. **Squash-merge** is the default. One commit per logical change.
+   The merge commit subject will become the PR title.
+
+## Code style
+
+- Match the existing style of the file you are editing.
+- Keep diffs minimal — don't reformat unrelated code.
+- Add tests for new behaviour. Bug fixes should add a regression test
+  that fails on `main` and passes on your branch.
+- No dead code, no commented-out code, no orphan TODO comments.
+
+## Security
+
+- **Never commit secrets, tokens, API keys, or `.env` files.**
+  Push-protection is on; if you bypass it, **rotate the credential**.
+  See [SECURITY.md](./SECURITY.md).
+- Don't paste stack traces that contain real user data in issues.
+- If you find a vulnerability, follow the
+  [private disclosure process](./SECURITY.md) — do not open a public
+  issue.
+
+## Dependencies
+
+- Dependabot opens weekly PRs for all package ecosystems detected
+  in the repo (npm, pip, cargo, docker, github-actions, gitsubmodule,
+  composer, gomod, bundler, nuget, maven, gradle).
+- Dependabot PRs are auto-mergeable when CI passes — they do not need
+  a review from a human (the branch is signed and the diff is small).
+- Major-version bumps that touch lockfiles will be reviewed manually.
+
+## Issue triage
+
+- New issues are auto-labelled **bug** / **enhancement** / **security**
+  via the issue templates.
+- Please use the right template. Issues without a template take longer
+  to triage.
+
+## License
+
+By submitting a contribution, you agree that your work will be
+licensed under the same license as the repository.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,43 +1,40 @@
 ---
 name: Bug report
-about: Create a report to help us improve
-title: '[BUG] '
+about: Something is broken
+title: "[bug] "
 labels: bug
-assignees: ''
-
+assignees: badhope
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+## Describe the bug
 
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+<!-- A clear and concise description of what the bug is. -->
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+## To reproduce
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+```bash
+# Minimal reproduction steps
+```
 
-**Environment (please complete the following information):**
- - OS: [e.g. Ubuntu 22.04]
- - Python Version: [e.g. 3.10]
- - DATA-AI Version: [e.g. 0.1.0]
- - Installation Method: [e.g. pip, source]
+## Expected behaviour
 
-**Configuration**
-```toml
-# Your config.toml (remove sensitive info)
-```
+<!-- What you expected to happen. -->
 
-**Logs**
-```
-Paste relevant logs here
-```
+## Actual behaviour
+
+<!-- What actually happened. Include stack traces, error messages,
+screenshots. -->
+
+## Environment
+
+- OS: <!-- e.g. macOS 14.4 -->
+- Runtime version: <!-- e.g. Node 20.11, Python 3.11 -->
+- Package version: <!-- git rev-parse HEAD, or npm/pip version -->
+- Date observed: <!-- 2026-06-10 -->
+
+## Severity
 
-**Additional context**
-Add any other context about the problem here.
+- [ ] Blocker — production is down
+- [ ] High — feature unusable
+- [ ] Medium — workaround exists
+- [ ] Low — cosmetic

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,23 +1,25 @@
 ---
 name: Feature request
-about: Suggest an idea for this project
-title: '[FEATURE] '
+about: Suggest an idea
+title: "[feat] "
 labels: enhancement
-assignees: ''
-
+assignees: badhope
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+## Problem
+
+<!-- What's the underlying problem or gap? -->
+
+## Proposed solution
+
+<!-- Describe the feature you'd like. -->
 
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
+## Alternatives considered
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
+<!-- Other ways you thought about solving this. -->
 
-**Use case**
-Describe the use case for this feature. Who would benefit from it?
+## Willingness to contribute
 
-**Additional context**
-Add any other context, mockups, or examples about the feature request here.
+- [ ] I would submit a PR for this
+- [ ] I would test a PR for this
+- [ ] I would only discuss / design

.github/ISSUE_TEMPLATE/security_report.md

@@ -0,0 +1,39 @@
+---
+name: Security report
+about: Report a vulnerability (PRIVATE)
+title: "[security] "
+labels: security
+assignees: badhope
+---
+
+> **Please do not disclose the vulnerability in a public issue.**
+> Use this private channel and the repository owner will respond within
+> 7 days. If you cannot wait, email the security contact listed in
+> [SECURITY.md](./SECURITY.md).
+
+## Summary
+
+<!-- One-paragraph summary of the vulnerability. -->
+
+## Affected component(s)
+
+- File(s):
+- Function(s) / endpoint(s):
+- Version / commit SHA:
+
+## Severity (your estimate)
+
+- [ ] Critical
+- [ ] High
+- [ ] Medium
+- [ ] Low
+
+## Reproduction
+
+```bash
+# Minimal steps / payload
+```
+
+## Impact
+
+<!-- What an attacker can do. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,27 +1,36 @@
 ## What
 
-<!-- One line: what this PR does -->
+<!-- One-paragraph description of the change. -->
 
 ## Why
 
-<!-- The reason. What problem does this fix / what value does it add? -->
+<!-- Motivation. Link any issue this PR fixes (Fixes #123). -->
 
 ## How
 
-<!-- Approach, breaking changes, anything weird you did -->
+<!-- Approach: list the changes, files touched, design decisions. -->
 
-## Tested
+## Test plan
 
-<!-- How you tested. If you didn't, say so and tell me why -->
+<!-- How did you verify? Which commands, which test suites? -->
 
-## Checklist
+- [ ] Existing tests pass
+- [ ] Added tests for new behaviour
+- [ ] Manually verified in dev / staging
+
+## Risk & rollout
 
-- [ ] I have read [`CONTRIBUTING.md`](./CONTRIBUTING.md)
-- [ ] Tests pass locally (and CI is green)
-- [ ] I didn't add any new linter / typecheck warnings
-- [ ] I didn't commit any secrets, build output, or large binaries
-- [ ] I added a `CHANGELOG.md` entry under "Unreleased" if it matters
+<!-- What can break? Is rollback straightforward? Is there a feature flag? -->
+
+## Checklist
 
-## Screenshots / Logs
+- [ ] My branch is up-to-date with the base branch
+- [ ] I ran `gitleaks` locally (or let CI do it)
+- [ ] I added / updated tests for new behaviour
+- [ ] I updated documentation (README, CHANGELOG, …)
+- [ ] I did **not** commit any secrets, tokens, or credentials
+- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
 
-<!-- Drag in images for UI changes. Paste (redacted) logs for runtime changes. -->
+> **Never commit secrets.** If you accidentally committed a token,
+> rotate it **immediately** in the provider's settings, then update
+> the PR to remove the secret. See [SECURITY.md](./SECURITY.md).