Add engineering documentation and repository hygiene checks

.github/REPOSITORY_SETTINGS.md

@@ -0,0 +1,9 @@
+# Suggested repository About settings
+
+These are prepared values, not a claim that GitHub account settings have been updated. The connected GitHub tools cannot edit these fields.
+
+- Description: LLM API gateway with provider adapters, API authentication, rate limiting, retries and signed webhooks.
+- Topics: python, fastapi, llm, redis, postgresql, api-gateway
+- Homepage: Leave blank until a public project URL is verified.
+
+For hosted applications, disclose account requirements and storage limitations in the README. Do not link a development server as a public demo.

.github/workflows/repository-hygiene.yml

@@ -0,0 +1,13 @@
+name: Repository hygiene
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  documentation-and-tracked-files:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python scripts/repository_check.py

.gitignore

@@ -10,3 +10,13 @@ htmlcov/
 dist/
 build/
 *.egg-info/
+
+# Local runtime and private configuration
+venv/
+node_modules/
+.env.local
+.env.*.local
+*.db
+*.sqlite
+*.sqlite3
+.DS_Store

README.md

@@ -53,3 +53,9 @@ This is a generation gateway, not a transparent implementation of every provider
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development checks, regression tests and review expectations. Use the issue templates for reproducible bugs or concrete feature proposals.
+
+## Engineering and contribution guide
+
+Read the [engineering notes](docs/ENGINEERING.md) for implementation boundaries and verification commands, the [review checklist](docs/REVIEW_CHECKLIST.md) for evidence still required, and [CONTRIBUTING.md](CONTRIBUTING.md) to propose changes. Report vulnerabilities through [SECURITY.md](SECURITY.md).
+
+[![Repository hygiene](https://github.com/Jemade/API-WRAPPER/actions/workflows/repository-hygiene.yml/badge.svg)](https://github.com/Jemade/API-WRAPPER/actions/workflows/repository-hygiene.yml)

SECURITY.md

@@ -0,0 +1,9 @@
+# Security reporting and deployment boundaries
+
+Report a suspected vulnerability privately to mapasurejayden@gmail.com with the repository, affected commit, reproduction steps and expected impact. Do not post credentials, customer data or exploit details in a public issue. Use GitHub private vulnerability reporting if it is enabled for this repository.
+
+No response-time or security certification is promised. The maintainer will assess the report and coordinate a fix when possible.
+
+Before public deployment, review authentication, authorization, data ownership, network exposure, secret handling, dependency advisories, logs and persistence for the intended environment. Local demos, mock providers and development Compose configurations are not proof of a secure production deployment.
+
+The repository hygiene check scans tracked files for selected credential patterns and runtime artifacts. It does not audit Git history or establish that every vulnerability or secret has been found. If an exposed credential is found, revoke or rotate it before addressing repository history.

docs/ENGINEERING.md

@@ -0,0 +1,41 @@
+# Engineering notes: API-WRAPPER
+
+## Purpose and scope
+
+Provider-neutral LLM API gateway. This repository is an independently inspectable project; customer adoption, production scale and commercial readiness are not claimed without evidence.
+
+## Request and data flow
+
+Authenticated generation request → rate limit → provider adapter and retries → response, request log and optional signed webhook.
+
+## Implementation map
+
+Primary implementation and review locations: `app/api`, `app/services`, `app/providers`. Dependency manifests and `.github/workflows/` specify installation and automated checks. Read the source for exact contracts and data models.
+
+## Local verification
+
+From `.` in a configured virtual environment:
+
+```sh
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy app
+pytest -q
+```
+
+From the repository root, run `python scripts/repository_check.py` for documentation and tracked-file checks. CI evidence is available in [GitHub Actions](https://github.com/Jemade/API-WRAPPER/actions). Green hygiene checks alone do not mean application tests passed.
+
+## Decisions and boundaries
+
+Live provider calls require credentials. Development tests use mocks. Review webhook destinations, authentication, database and Redis configuration before exposing the service.
+
+Use the README's current run instructions and configuration examples. Keep provider credentials outside Git. Test changes against controlled fixtures before enabling external services. Health checks indicate process/service state, not end-to-end correctness.
+
+## Review and operational evidence
+
+[Review checklist](REVIEW_CHECKLIST.md) distinguishes repository evidence from outstanding human and deployment validation. Report measured workload, environment and method with any performance claim. Document incident fixes through reproducible issues and regression tests; do not invent user counts or peer reviews.
+
+## Reuse and licensing
+
+The root LICENSE describes the repository license. Third-party dependencies and assets retain their respective licenses.

docs/REVIEW_CHECKLIST.md

@@ -0,0 +1,34 @@
+# Repository review checklist
+
+Reviewed baseline: 4 October 2026. This is an evidence checklist, not a hiring score or security certification.
+
+## Repository evidence
+
+- [x] README identifies the purpose, implementation and local run path.
+- [x] Engineering notes describe data flow, implementation locations and product boundaries.
+- [x] Contributor instructions and bug/feature forms exist.
+- [x] Pull-request template asks for the problem, tradeoffs and actual validation.
+- [x] Security reporting and deployment boundaries are documented.
+- [x] A repeatable tracked-file and documentation check is included in CI.
+- [x] Current scope and limitations are stated without invented adoption or performance claims.
+- [x] Repository-wide reuse license selected; confirm third-party rights independently.
+
+## Evidence to check for a specific release
+
+- [ ] Application tests, builds and required integrations pass at the release commit. Follow the Actions link in engineering notes; a past successful run is not proof of a new release.
+- [ ] A clean installation and the main user workflow have been demonstrated in the target environment.
+- [ ] Authentication and authorization are reviewed for the intended deployment, where applicable.
+- [ ] Dependency advisories and all applicable secrets are reviewed; the bounded pattern scan is not sufficient on its own.
+- [ ] Persistence, backup/recovery and failure behavior are verified in the intended environment, where applicable.
+- [ ] Performance statements include an actual workload, measurement and environment.
+- [ ] Screenshot or walkthrough reflects the current release.
+
+## Human and external evidence
+
+- [ ] An independent engineer has reviewed relevant code and the review is recorded.
+- [ ] The owner can explain and modify the implementation independently.
+- [ ] Actual user feedback is recorded when real users exist; synthetic fixtures are identified.
+- [ ] Resume claims match work the owner personally performed and can substantiate.
+- [ ] Third-party contributions, attribution and asset rights have been checked.
+
+Unchecked items require actual evidence. Items genuinely irrelevant to a project should be marked not applicable with a reason during release review.

scripts/repository_check.py

@@ -0,0 +1,62 @@
+"""Check tracked repository hygiene and required contributor documentation.
+
+This is a bounded pattern scan, not a security certification or history scan.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+REQUIRED = (
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs/ENGINEERING.md",
+    "docs/REVIEW_CHECKLIST.md",
+    ".gitignore",
+    ".github/pull_request_template.md",
+    ".github/ISSUE_TEMPLATE/bug_report.yml",
+    ".github/ISSUE_TEMPLATE/feature_request.yml",
+)
+SECRET_PATTERNS = (
+    re.compile(r"gh[pousr]_[A-Za-z0-9]{30,}"),
+    re.compile(r"github_pat_[A-Za-z0-9_]{50,}"),
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    re.compile(r"AIza[0-9A-Za-z_-]{35}"),
+    re.compile(r"(?m)^-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----$"),
+)
+
+
+def main():
+    errors = ["Missing " + name for name in REQUIRED if not (ROOT / name).is_file()]
+    tracked = subprocess.check_output(["git", "ls-files", "-z"], cwd=ROOT).decode().split("\0")
+    for name in filter(None, tracked):
+        path = Path(name)
+        if (
+            any(part in {".venv", "venv", "node_modules", "__pycache__"} for part in path.parts)
+            or path.name == ".env"
+            or path.suffix in {".pyc", ".db", ".sqlite", ".sqlite3"}
+        ):
+            errors.append("Runtime or private file tracked: " + name)
+        file = ROOT / name
+        if not file.is_file() or file.stat().st_size > 1_000_000:
+            continue
+        try:
+            content = file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        if any(pattern.search(content) for pattern in SECRET_PATTERNS):
+            errors.append("Possible credential in " + name + "; inspect privately")
+    if errors:
+        print("\n".join(errors))
+        raise SystemExit(1)
+    print(
+        "Required documentation and tracked-file checks passed. "
+        "Pattern scan found no matching credentials; "
+        "history and other credential formats are outside this check."
+    )
+
+
+if __name__ == "__main__":
+    main()