Surface flagship projects and add a public engineering review index

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report a reproducible defect
+title: "bug: "
+body:
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Include the smallest reproducible example using synthetic data.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected and actual behavior
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Commit, Python version, OS and relevant deployment mode.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Sanitized logs or failing test
+      description: Remove credentials and private data before posting.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Propose an improvement grounded in a user need
+title: "feature: "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: User problem
+      description: Who needs this and what can they not do today?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Proposed outcome and acceptance criteria
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives and tradeoffs

.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: Jayden Mapasure: Python and JavaScript software engineering projects and experience.
+- Topics: portfolio, python, javascript, software-engineer
+- Homepage: https://jemade.github.io/portfolio/
+
+For hosted applications, disclose account requirements and storage limitations in the README. Do not link a development server as a public demo.

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Problem and resulting behavior
+
+Describe the concrete trigger, previous behavior and new behavior.
+
+Closes #<issue number>
+
+## Implementation and tradeoffs
+
+Explain the smallest useful change and any compatibility or operational risks.
+
+## Validation
+
+- Regression demonstrated before the fix:
+- Checks run and results:
+- Checks skipped and reason:
+
+## Review focus
+
+Identify the edge cases or decisions that need another engineer's attention.

.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

@@ -0,0 +1,18 @@
+
+
+# Local runtime and private configuration
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+.env
+.env.local
+.env.*.local
+*.db
+*.sqlite
+*.sqlite3
+.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing to portfolio
+
+Start with a reproducible defect or a concrete user need. Search existing issues and keep changes focused.
+
+## Development checks
+
+Use a Python virtual environment. From `.`, run:
+
+```sh
+python scripts/repository_check.py
+python -m http.server 8000
+```
+
+Read the README for runtime versions and service prerequisites. Additional CI jobs are defined in `.github/workflows/`; do not describe a skipped check as passed.
+
+For a behavior fix, add a regression that fails before the fix and passes afterward. Explain expected and actual behavior, link the issue from the PR, and document tradeoffs. Use synthetic fixtures and never publish credentials or private data.
+
+A review should check correctness, boundaries, failure handling and tests. Independent review is distinct from automated checks. Follow [SECURITY.md](SECURITY.md) for vulnerability reports and [engineering notes](docs/ENGINEERING.md) for product boundaries.

README.md

@@ -2,14 +2,16 @@
 
 Personal portfolio for my Python and JavaScript work: backend services, APIs, web applications, automation, and practical AI integrations.
 
-[View portfolio](https://jemade.github.io/portfolio/) · [GitHub](https://github.com/Jemade) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure)
+[View portfolio](https://jemade.github.io/portfolio/) · [GitHub](https://github.com/Jemade) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure-013410323/)
 
 ## Featured work
 
 | Project | Focus |
 | --- | --- |
 | [BridgeSync](https://github.com/Jemade/BridgeSync) | Order delivery, durable jobs, and payment reconciliation |
 | [AgentBench](https://github.com/Jemade/AgentBench) | Python coding-agent evaluation and inspectable evidence |
+| [RAG System](https://github.com/Jemade/RAG-SYSTEM) | Retrieval telemetry, evidence checks and evaluation |
+| [Personal Workspace MCP](https://github.com/Jemade/MCP-SERVER) | Tasks, read-only SQLite analytics and weather tools |
 | [Relay](https://github.com/Jemade/Relay) | Conversation evaluation and streaming progress |
 | [FlowOps](https://github.com/Jemade/flowOPS) | Data pipeline orchestration |
 | [LLM API Gateway](https://github.com/Jemade/API-WRAPPER) | Provider integration, authentication, and rate limiting |
@@ -38,3 +40,9 @@ Open http://localhost:8000.
 - `.github/workflows/`: GitHub Pages deployment.
 
 Google Fonts, Devicon, and Lucide load from external providers. The site can be served by any static web host.
+
+## 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/portfolio/actions/workflows/repository-hygiene.yml/badge.svg)](https://github.com/Jemade/portfolio/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,38 @@
+# Engineering notes: portfolio
+
+## Purpose and scope
+
+Python and JavaScript engineering portfolio. This repository is an independently inspectable project; customer adoption, production scale and commercial readiness are not claimed without evidence.
+
+## Request and data flow
+
+Static HTML content and assets → CSS layout and browser behavior → GitHub Pages deployment.
+
+## Implementation map
+
+Primary implementation and review locations: `index.html`, `style.css`, `script.js`, `assets`. 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
+python scripts/repository_check.py
+python -m http.server 8000
+```
+
+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/portfolio/actions). Green hygiene checks alone do not mean application tests passed.
+
+## Decisions and boundaries
+
+Static presentation rather than a backend product. Fonts and icons depend on external providers. Experience claims are owner-supplied; engineering projects should link to verifiable source and limitations.
+
+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
+
+No repository-wide reuse license has been selected. Public visibility alone does not grant an open-source reuse license. Ownership and third-party asset rights must be confirmed before licensing this project.

docs/PROFILE_README.md

@@ -0,0 +1,19 @@
+# Jayden Takudzwa Mapasure
+
+Software Engineer based in Harare, Zimbabwe. I build backend services, APIs, web applications, automation and practical AI integrations with Python and JavaScript.
+
+[Portfolio](https://jemade.github.io/portfolio/) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure-013410323/) · [Contact](mailto:mapasurejayden@gmail.com)
+
+## Selected engineering work
+
+| Project | What to inspect |
+| --- | --- |
+| [BridgeSync](https://github.com/Jemade/BridgeSync) | Durable delivery, reconciliation, isolation and regression tests |
+| [AgentBench](https://github.com/Jemade/AgentBench) | Sandbox execution, verifier correctness and evaluation evidence |
+| [RAG System](https://github.com/Jemade/RAG-SYSTEM) | Retrieval telemetry, grounding checks and evaluation harness |
+| [Personal Workspace MCP](https://github.com/Jemade/MCP-SERVER) | Safe local tools, SQLite access and weather integration |
+| [LLM API Gateway](https://github.com/Jemade/API-WRAPPER) | Provider abstraction, authentication, rate limiting and webhooks |
+
+Each repository documents its setup and current limitations. Read the implementation and test evidence rather than treating demo output as a production claim.
+
+University of Zimbabwe, B.S. Artificial Intelligence and Machine Learning, 2024–2028. Open to remote software engineering opportunities.

docs/PROJECT_REVIEW.md

@@ -0,0 +1,53 @@
+# Public project review
+
+Baseline prepared on 4 October 2026. The repository links below provide source code, setup instructions, CI and documented limitations. This review does not certify production security, customer adoption or engineering ownership.
+
+## Project index
+
+| Repository | Automated evidence | Implementation notes | Licensing status | Inspected source base |
+| --- | --- | --- | --- | --- |
+| [API-WRAPPER](https://github.com/Jemade/API-WRAPPER) | [Checks](https://github.com/Jemade/API-WRAPPER/actions) | [Engineering](https://github.com/Jemade/API-WRAPPER/blob/main/docs/ENGINEERING.md) | MIT present | `76f199e` |
+| [AgentBench](https://github.com/Jemade/AgentBench) | [Checks](https://github.com/Jemade/AgentBench/actions) | [Engineering](https://github.com/Jemade/AgentBench/blob/main/docs/ENGINEERING.md) | MIT present | `798dae6` |
+| [Avantis-support](https://github.com/Jemade/Avantis-support) | [Checks](https://github.com/Jemade/Avantis-support/actions) | [Engineering](https://github.com/Jemade/Avantis-support/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `82319c4` |
+| [BridgeSync](https://github.com/Jemade/BridgeSync) | [Checks](https://github.com/Jemade/BridgeSync/actions) | [Engineering](https://github.com/Jemade/BridgeSync/blob/main/docs/ENGINEERING.md) | MIT present | `3001aa7` |
+| [Human-in-the-loop](https://github.com/Jemade/Human-in-the-loop) | [Checks](https://github.com/Jemade/Human-in-the-loop/actions) | [Engineering](https://github.com/Jemade/Human-in-the-loop/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `5f495ce` |
+| [MCP-SERVER](https://github.com/Jemade/MCP-SERVER) | [Checks](https://github.com/Jemade/MCP-SERVER/actions) | [Engineering](https://github.com/Jemade/MCP-SERVER/blob/main/docs/ENGINEERING.md) | MIT present | `6747293` |
+| [RAG-SYSTEM](https://github.com/Jemade/RAG-SYSTEM) | [Checks](https://github.com/Jemade/RAG-SYSTEM/actions) | [Engineering](https://github.com/Jemade/RAG-SYSTEM/blob/main/docs/ENGINEERING.md) | MIT present | `20c2965` |
+| [Relay](https://github.com/Jemade/Relay) | [Checks](https://github.com/Jemade/Relay/actions) | [Engineering](https://github.com/Jemade/Relay/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `04d2c59` |
+| [Streaming-Copilot-Ui](https://github.com/Jemade/Streaming-Copilot-Ui) | [Checks](https://github.com/Jemade/Streaming-Copilot-Ui/actions) | [Engineering](https://github.com/Jemade/Streaming-Copilot-Ui/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `6817041` |
+| [Vetta](https://github.com/Jemade/Vetta) | [Checks](https://github.com/Jemade/Vetta/actions) | [Engineering](https://github.com/Jemade/Vetta/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `af71b77` |
+| [cited-RAG-BOT](https://github.com/Jemade/cited-RAG-BOT) | [Checks](https://github.com/Jemade/cited-RAG-BOT/actions) | [Engineering](https://github.com/Jemade/cited-RAG-BOT/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `2a4c01e` |
+| [flowOPS](https://github.com/Jemade/flowOPS) | [Checks](https://github.com/Jemade/flowOPS/actions) | [Engineering](https://github.com/Jemade/flowOPS/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `ede42c6` |
+| [llm-cost-guard](https://github.com/Jemade/llm-cost-guard) | [Checks](https://github.com/Jemade/llm-cost-guard/actions) | [Engineering](https://github.com/Jemade/llm-cost-guard/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `dcf4173` |
+| [portfolio](https://github.com/Jemade/portfolio) | [Checks](https://github.com/Jemade/portfolio/actions) | [Engineering](https://github.com/Jemade/portfolio/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `4517911` |
+| [valid_json_Agent](https://github.com/Jemade/valid_json_Agent) | [Checks](https://github.com/Jemade/valid_json_Agent/actions) | [Engineering](https://github.com/Jemade/valid_json_Agent/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `19fe8a9` |
+
+## Work completed in this review
+
+- Merged the five previously tested fixes for BridgeSync, AgentBench, RAG System, MCP Server and the LLM API Gateway.
+- Added contributor instructions, issue forms, PR templates, security reporting, engineering notes, tracked-file checks and review checklists across all public repositories.
+- Fixed existing lint/type/dependency issues in LLM Cost Guard and the async dependency in Relay.
+- Added VETTA application CI and PC Assist backend/frontend CI with deterministic cache and platform-fallback checks.
+- Updated portfolio links and added the four missing flagship project cards.
+
+Follow the actual Actions run for the commit being assessed. A green documentation check does not replace application tests, browser checks or deployment verification.
+
+## Profile settings prepared for the account owner
+
+The GitHub connector used for this review cannot edit account profile fields, pins, repository About fields or create the special profile repository.
+
+- Suggested bio: Software Engineer | Python & JavaScript | Backend systems, APIs, automation and practical AI integrations | Harare, Zimbabwe
+- Website: https://jemade.github.io/portfolio/
+- LinkedIn: https://www.linkedin.com/in/jayden-mapasure-013410323/
+- Suggested pins: BridgeSync, AgentBench, RAG-SYSTEM, MCP-SERVER, API-WRAPPER and portfolio.
+- [Profile README draft](PROFILE_README.md): publish as README.md in a public repository named Jemade/Jemade when that repository exists.
+
+## Evidence still requiring real validation
+
+- Independent peer review and contribution discussions cannot be created by marking an automated review as a human review.
+- The owner must demonstrate code understanding and verify resume claims.
+- Real users, feedback, adoption and performance measurements must be earned and recorded, not fabricated.
+- Licenses cannot be selected for code or assets without confirming the owner's rights and intended reuse terms.
+- A private SSH key found in LLM Cost Guard was removed from the current files. It remains in prior Git history and must be revoked wherever it was authorized. Current-file scanning does not resolve that historical exposure.
+- Public demos that require account access need a safe reviewer-access workflow. Production persistence, backups and recovery require deployment-specific checks.
+- Windows installation and hardware behavior need actual target-device testing; mocked helper tests are insufficient.

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.
+- [ ] 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.