docs: contributor experience overhaul

Makefile
- make check (lint + typecheck + tests) — the one command before every PR
- make test, make lint, make typecheck, make bench, make fix, make clean

CONTRIBUTING.md (rewritten from scratch)
- Quick start with make install + make check
- Architecture in 30 seconds (ASCII flow + file map)
- The Three Rules (never raise, never mutate, zero deps)
- Gotchas section (callable module trick, _serialize vs _minimize,
  __future__ annotations, precompiled regexes, pragma preservation,
  thread safety)
- Full minimizer template with step-by-step checklist
- Testing philosophy (feature tests vs adversarial tests)
- PR etiquette

GitHub templates
- PR template with checklist (make check, tests, no new deps, docs)
- Bug report issue form (reproduction, traceback, versions)
- Feature request issue form (problem, proposal, example, scope)

Pre-commit config (ruff + mypy)

Fixes
- pyproject.toml URLs pointed to ptk-ai/ptk, now amahi2001/python-token-killer
- Added Issues + Changelog URLs to project.urls
- Added ruff, mypy, pre-commit to dev dependencies
- Ran ruff format across all source files
- AGENTS.md updated to reference Makefile commands

Author: amahi2001

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug Report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect vs what actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: The smallest code snippet that triggers the bug.
+      render: python
+      placeholder: |
+        import ptk
+        result = ptk.minimize(...)  # expected X, got Y
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback (if applicable)
+      description: Full error traceback.
+      render: text
+
+  - type: input
+    id: ptk-version
+    attributes:
+      label: ptk version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature Request
+description: Suggest a new minimizer, compression strategy, or API improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: What are you trying to minimize, and why doesn't ptk handle it well today?
+      placeholder: "I have [type of data] that ptk currently treats as text, but it could save more tokens by..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How should ptk handle this? New minimizer? Improvement to an existing one? New API option?
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example input/output
+      description: Show a before (original) and after (what the minimized output should look like).
+      render: python
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - New minimizer
+        - Improvement to existing minimizer
+        - New output format
+        - API change
+        - Detection improvement
+        - Other
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What
+
+<!-- One sentence: what does this PR do? -->
+
+## Why
+
+<!-- What problem does it solve? Link to issue if applicable. -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New minimizer
+- [ ] Improvement to existing minimizer
+- [ ] Documentation
+- [ ] Tests
+- [ ] Other: <!-- describe -->
+
+## Checklist
+
+- [ ] `make check` passes (lint + typecheck + tests)
+- [ ] New code has tests in `test_ptk.py` (feature) and/or `test_adversarial.py` (edge cases)
+- [ ] No new required dependencies added (optional extras are fine)
+- [ ] Docstrings on new public classes/methods
+- [ ] CHANGELOG.md updated under `[Unreleased]` if user-facing
+
+## For New Minimizers Only
+
+- [ ] Detection heuristic added to `_types.py`
+- [ ] Registered in `_ROUTER` in `__init__.py`
+- [ ] Exported from `minimizers/__init__.py`
+- [ ] Sample input added to `TestAPIContracts.SAMPLE_INPUTS`
+- [ ] Content type mismatch test added
+- [ ] Benchmark data included in PR description

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.0
+    hooks:
+      - id: mypy
+        args: [--strict]
+        additional_dependencies: []
+        files: ^src/ptk/

AGENTS.md

@@ -34,17 +34,12 @@ ptk.minimize(obj) → _types.detect(obj) → _ROUTER[type].run(obj) → MinResul
 ## Commands
 
 ```bash
-# run tests (322 tests, <0.5s)
-PYTHONPATH=src python -m pytest tests/ -v
-
-# run benchmarks (requires tiktoken)
-python benchmarks/bench.py
-
-# type check
-mypy --strict src/ptk/
-
-# lint
-ruff check src/ tests/
+make check      # lint + typecheck + tests — run before every commit
+make test       # tests only (322 tests, <0.5s)
+make lint       # ruff check + format check
+make typecheck  # mypy --strict
+make bench      # benchmarks with tiktoken
+make fix        # auto-fix lint/formatting
 ```
 
 ## Test Structure